diff --git a/.github/ISSUE_TEMPLATE/01_bugs.md b/.github/ISSUE_TEMPLATE/01_bugs.md
index 768832c24..f0d0ba912 100644
--- a/.github/ISSUE_TEMPLATE/01_bugs.md
+++ b/.github/ISSUE_TEMPLATE/01_bugs.md
@@ -4,11 +4,13 @@ about: Use this template if you came across a bug or unexpected behaviour differ
---
+
+
## How to reproduce the behaviour
## Your Environment
-
+
* Operating System:
* Python Version Used:
* spaCy Version Used:
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index fce1a1064..31f89f917 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -1,8 +1,5 @@
blank_issues_enabled: false
contact_links:
- - name: ⚠️ Python 3.10 Support
- url: https://github.com/explosion/spaCy/discussions/9418
- about: Python 3.10 wheels haven't been released yet, see the link for details.
- name: 🗯 Discussions Forum
url: https://github.com/explosion/spaCy/discussions
about: Install issues, usage questions, general discussion and anything else that isn't a bug report.
diff --git a/.github/azure-steps.yml b/.github/azure-steps.yml
index 80c88b0b8..ed69f611b 100644
--- a/.github/azure-steps.yml
+++ b/.github/azure-steps.yml
@@ -1,68 +1,56 @@
parameters:
python_version: ''
- architecture: ''
- prefix: ''
- gpu: false
- num_build_jobs: 1
+ architecture: 'x64'
+ num_build_jobs: 2
steps:
- task: UsePythonVersion@0
inputs:
versionSpec: ${{ parameters.python_version }}
architecture: ${{ parameters.architecture }}
+ allowUnstable: true
- bash: |
echo "##vso[task.setvariable variable=python_version]${{ parameters.python_version }}"
displayName: 'Set variables'
- script: |
- ${{ parameters.prefix }} python -m pip install -U pip setuptools
- ${{ parameters.prefix }} python -m pip install -U -r requirements.txt
+ python -m pip install -U build pip setuptools
+ python -m pip install -U -r requirements.txt
displayName: "Install dependencies"
- script: |
- ${{ parameters.prefix }} python setup.py build_ext --inplace -j ${{ parameters.num_build_jobs }}
- ${{ parameters.prefix }} python setup.py sdist --formats=gztar
- displayName: "Compile and build sdist"
+ python -m build --sdist
+ displayName: "Build sdist"
- - script: python -m mypy spacy
+ - script: |
+ python -m mypy spacy
displayName: 'Run mypy'
- condition: ne(variables['python_version'], '3.10')
+ condition: ne(variables['python_version'], '3.6')
- task: DeleteFiles@1
inputs:
contents: "spacy"
displayName: "Delete source directory"
+ - task: DeleteFiles@1
+ inputs:
+ contents: "*.egg-info"
+ displayName: "Delete egg-info directory"
+
- script: |
- ${{ parameters.prefix }} python -m pip freeze --exclude torch --exclude cupy-cuda110 > installed.txt
- ${{ parameters.prefix }} python -m pip uninstall -y -r installed.txt
+ python -m pip freeze > installed.txt
+ python -m pip uninstall -y -r installed.txt
displayName: "Uninstall all packages"
- bash: |
- ${{ parameters.prefix }} SDIST=$(python -c "import os;print(os.listdir('./dist')[-1])" 2>&1)
- ${{ parameters.prefix }} python -m pip install dist/$SDIST
+ SDIST=$(python -c "import os;print(os.listdir('./dist')[-1])" 2>&1)
+ SPACY_NUM_BUILD_JOBS=${{ parameters.num_build_jobs }} python -m pip install dist/$SDIST
displayName: "Install from sdist"
- script: |
- ${{ parameters.prefix }} python -m pip install -U -r requirements.txt
- displayName: "Install test requirements"
-
- - script: |
- ${{ parameters.prefix }} python -m pip install -U cupy-cuda110 -f https://github.com/cupy/cupy/releases/v9.0.0
- ${{ parameters.prefix }} python -m pip install "torch==1.7.1+cu110" -f https://download.pytorch.org/whl/torch_stable.html
- displayName: "Install GPU requirements"
- condition: eq(${{ parameters.gpu }}, true)
-
- - script: |
- ${{ parameters.prefix }} python -m pytest --pyargs spacy
- displayName: "Run CPU tests"
- condition: eq(${{ parameters.gpu }}, false)
-
- - script: |
- ${{ parameters.prefix }} python -m pytest --pyargs spacy -p spacy.tests.enable_gpu
- displayName: "Run GPU tests"
- condition: eq(${{ parameters.gpu }}, true)
+ python -W error -c "import spacy"
+ displayName: "Test import"
- script: |
python -m spacy download ca_core_news_sm
@@ -71,6 +59,11 @@ steps:
displayName: 'Test download CLI'
condition: eq(variables['python_version'], '3.8')
+ - script: |
+ python -W error -c "import ca_core_news_sm; nlp = ca_core_news_sm.load(); doc=nlp('test')"
+ displayName: 'Test no warnings on load (#11713)'
+ condition: eq(variables['python_version'], '3.8')
+
- script: |
python -m spacy convert extra/example_data/ner_example_data/ner-token-per-line-conll2003.json .
displayName: 'Test convert CLI'
@@ -105,13 +98,22 @@ steps:
displayName: 'Test assemble CLI vectors warning'
condition: eq(variables['python_version'], '3.8')
+ - script: |
+ python -m pip install -U -r requirements.txt
+ displayName: "Install test requirements"
+
+ - script: |
+ python -m pytest --pyargs spacy -W error
+ displayName: "Run CPU tests"
+
+ - script: |
+ python -m pip install 'spacy[apple]'
+ python -m pytest --pyargs spacy
+ displayName: "Run CPU tests with thinc-apple-ops"
+ condition: and(startsWith(variables['imageName'], 'macos'), eq(variables['python.version'], '3.11'))
+
- script: |
python .github/validate_universe_json.py website/meta/universe.json
displayName: 'Test website/meta/universe.json'
condition: eq(variables['python_version'], '3.8')
- - script: |
- ${{ parameters.prefix }} python -m pip install thinc-apple-ops
- ${{ parameters.prefix }} python -m pytest --pyargs spacy
- displayName: "Run CPU tests with thinc-apple-ops"
- condition: and(startsWith(variables['imageName'], 'macos'), eq(variables['python.version'], '3.9'))
diff --git a/.github/contributors/Lucaterre.md b/.github/contributors/Lucaterre.md
new file mode 100644
index 000000000..5da763b22
--- /dev/null
+++ b/.github/contributors/Lucaterre.md
@@ -0,0 +1,106 @@
+# spaCy contributor agreement
+
+This spaCy Contributor Agreement (**"SCA"**) is based on the
+[Oracle Contributor Agreement](http://www.oracle.com/technetwork/oca-405177.pdf).
+The SCA applies to any contribution that you make to any product or project
+managed by us (the **"project"**), and sets out the intellectual property rights
+you grant to us in the contributed materials. The term **"us"** shall mean
+[ExplosionAI GmbH](https://explosion.ai/legal). The term
+**"you"** shall mean the person or entity identified below.
+
+If you agree to be bound by these terms, fill in the information requested
+below and include the filled-in version with your first pull request, under the
+folder [`.github/contributors/`](/.github/contributors/). The name of the file
+should be your GitHub username, with the extension `.md`. For example, the user
+example_user would create the file `.github/contributors/example_user.md`.
+
+Read this agreement carefully before signing. These terms and conditions
+constitute a binding legal agreement.
+
+## Contributor Agreement
+
+1. The term "contribution" or "contributed materials" means any source code,
+object code, patch, tool, sample, graphic, specification, manual,
+documentation, or any other material posted or submitted by you to the project.
+
+2. With respect to any worldwide copyrights, or copyright applications and
+registrations, in your contribution:
+
+ * you hereby assign to us joint ownership, and to the extent that such
+ assignment is or becomes invalid, ineffective or unenforceable, you hereby
+ grant to us a perpetual, irrevocable, non-exclusive, worldwide, no-charge,
+ royalty-free, unrestricted license to exercise all rights under those
+ copyrights. This includes, at our option, the right to sublicense these same
+ rights to third parties through multiple levels of sublicensees or other
+ licensing arrangements;
+
+ * you agree that each of us can do all things in relation to your
+ contribution as if each of us were the sole owners, and if one of us makes
+ a derivative work of your contribution, the one who makes the derivative
+ work (or has it made will be the sole owner of that derivative work;
+
+ * you agree that you will not assert any moral rights in your contribution
+ against us, our licensees or transferees;
+
+ * you agree that we may register a copyright in your contribution and
+ exercise all ownership rights associated with it; and
+
+ * you agree that neither of us has any duty to consult with, obtain the
+ consent of, pay or render an accounting to the other for any use or
+ distribution of your contribution.
+
+3. With respect to any patents you own, or that you can license without payment
+to any third party, you hereby grant to us a perpetual, irrevocable,
+non-exclusive, worldwide, no-charge, royalty-free license to:
+
+ * make, have made, use, sell, offer to sell, import, and otherwise transfer
+ your contribution in whole or in part, alone or in combination with or
+ included in any product, work or materials arising out of the project to
+ which your contribution was submitted, and
+
+ * at our option, to sublicense these same rights to third parties through
+ multiple levels of sublicensees or other licensing arrangements.
+
+4. Except as set out above, you keep all right, title, and interest in your
+contribution. The rights that you grant to us under these terms are effective
+on the date you first submitted a contribution to us, even if your submission
+took place before the date you sign these terms.
+
+5. You covenant, represent, warrant and agree that:
+
+ * Each contribution that you submit is and shall be an original work of
+ authorship and you can legally grant the rights set out in this SCA;
+
+ * to the best of your knowledge, each contribution will not violate any
+ third party's copyrights, trademarks, patents, or other intellectual
+ property rights; and
+
+ * each contribution shall be in compliance with U.S. export control laws and
+ other applicable export and import laws. You agree to notify us if you
+ become aware of any circumstance which would make any of the foregoing
+ representations inaccurate in any respect. We may publicly disclose your
+ participation in the project, including the fact that you have signed the SCA.
+
+6. This SCA is governed by the laws of the State of California and applicable
+U.S. Federal law. Any choice of law rules will not apply.
+
+7. Please place an “x” on one of the applicable statement below. Please do NOT
+mark both statements:
+
+ * [x] I am signing on behalf of myself as an individual and no other person
+ or entity, including my employer, has or will have rights with respect to my
+ contributions.
+
+ * [ ] I am signing on behalf of my employer or a legal entity and I have the
+ actual authority to contractually bind that entity.
+
+## Contributor Details
+
+| Field | Entry |
+|------------------------------- |---------------|
+| Name | Lucas Terriel |
+| Company name (if applicable) | |
+| Title or role (if applicable) | |
+| Date | 2022-06-20 |
+| GitHub username | Lucaterre |
+| Website (optional) | |
\ No newline at end of file
diff --git a/.github/contributors/fonfonx.md b/.github/contributors/fonfonx.md
new file mode 100644
index 000000000..7fb01ca5a
--- /dev/null
+++ b/.github/contributors/fonfonx.md
@@ -0,0 +1,106 @@
+# spaCy contributor agreement
+
+This spaCy Contributor Agreement (**"SCA"**) is based on the
+[Oracle Contributor Agreement](http://www.oracle.com/technetwork/oca-405177.pdf).
+The SCA applies to any contribution that you make to any product or project
+managed by us (the **"project"**), and sets out the intellectual property rights
+you grant to us in the contributed materials. The term **"us"** shall mean
+[ExplosionAI GmbH](https://explosion.ai/legal). The term
+**"you"** shall mean the person or entity identified below.
+
+If you agree to be bound by these terms, fill in the information requested
+below and include the filled-in version with your first pull request, under the
+folder [`.github/contributors/`](/.github/contributors/). The name of the file
+should be your GitHub username, with the extension `.md`. For example, the user
+example_user would create the file `.github/contributors/example_user.md`.
+
+Read this agreement carefully before signing. These terms and conditions
+constitute a binding legal agreement.
+
+## Contributor Agreement
+
+1. The term "contribution" or "contributed materials" means any source code,
+object code, patch, tool, sample, graphic, specification, manual,
+documentation, or any other material posted or submitted by you to the project.
+
+2. With respect to any worldwide copyrights, or copyright applications and
+registrations, in your contribution:
+
+ * you hereby assign to us joint ownership, and to the extent that such
+ assignment is or becomes invalid, ineffective or unenforceable, you hereby
+ grant to us a perpetual, irrevocable, non-exclusive, worldwide, no-charge,
+ royalty-free, unrestricted license to exercise all rights under those
+ copyrights. This includes, at our option, the right to sublicense these same
+ rights to third parties through multiple levels of sublicensees or other
+ licensing arrangements;
+
+ * you agree that each of us can do all things in relation to your
+ contribution as if each of us were the sole owners, and if one of us makes
+ a derivative work of your contribution, the one who makes the derivative
+ work (or has it made will be the sole owner of that derivative work;
+
+ * you agree that you will not assert any moral rights in your contribution
+ against us, our licensees or transferees;
+
+ * you agree that we may register a copyright in your contribution and
+ exercise all ownership rights associated with it; and
+
+ * you agree that neither of us has any duty to consult with, obtain the
+ consent of, pay or render an accounting to the other for any use or
+ distribution of your contribution.
+
+3. With respect to any patents you own, or that you can license without payment
+to any third party, you hereby grant to us a perpetual, irrevocable,
+non-exclusive, worldwide, no-charge, royalty-free license to:
+
+ * make, have made, use, sell, offer to sell, import, and otherwise transfer
+ your contribution in whole or in part, alone or in combination with or
+ included in any product, work or materials arising out of the project to
+ which your contribution was submitted, and
+
+ * at our option, to sublicense these same rights to third parties through
+ multiple levels of sublicensees or other licensing arrangements.
+
+4. Except as set out above, you keep all right, title, and interest in your
+contribution. The rights that you grant to us under these terms are effective
+on the date you first submitted a contribution to us, even if your submission
+took place before the date you sign these terms.
+
+5. You covenant, represent, warrant and agree that:
+
+ * Each contribution that you submit is and shall be an original work of
+ authorship and you can legally grant the rights set out in this SCA;
+
+ * to the best of your knowledge, each contribution will not violate any
+ third party's copyrights, trademarks, patents, or other intellectual
+ property rights; and
+
+ * each contribution shall be in compliance with U.S. export control laws and
+ other applicable export and import laws. You agree to notify us if you
+ become aware of any circumstance which would make any of the foregoing
+ representations inaccurate in any respect. We may publicly disclose your
+ participation in the project, including the fact that you have signed the SCA.
+
+6. This SCA is governed by the laws of the State of California and applicable
+U.S. Federal law. Any choice of law rules will not apply.
+
+7. Please place an “x” on one of the applicable statement below. Please do NOT
+mark both statements:
+
+ * [x] I am signing on behalf of myself as an individual and no other person
+ or entity, including my employer, has or will have rights with respect to my
+ contributions.
+
+ * [ ] I am signing on behalf of my employer or a legal entity and I have the
+ actual authority to contractually bind that entity.
+
+## Contributor Details
+
+| Field | Entry |
+|------------------------------- | -------------------- |
+| Name | Xavier Fontaine |
+| Company name (if applicable) | |
+| Title or role (if applicable) | |
+| Date | 2022-04-13 |
+| GitHub username | fonfonx |
+| Website (optional) | |
diff --git a/.github/no-response.yml b/.github/no-response.yml
deleted file mode 100644
index ea78104b9..000000000
--- a/.github/no-response.yml
+++ /dev/null
@@ -1,13 +0,0 @@
-# Configuration for probot-no-response - https://github.com/probot/no-response
-
-# Number of days of inactivity before an Issue is closed for lack of response
-daysUntilClose: 14
-# Label requiring a response
-responseRequiredLabel: more-info-needed
-# Comment to post when closing an Issue for lack of response. Set to `false` to disable
-closeComment: >
- This issue has been automatically closed because there has been no response
- to a request for more information from the original author. With only the
- information that is currently in the issue, there's not enough information
- to take action. If you're the original author, feel free to reopen the issue
- if you have or find the answers needed to investigate further.
diff --git a/.github/spacy_universe_alert.py b/.github/spacy_universe_alert.py
new file mode 100644
index 000000000..99ffabe93
--- /dev/null
+++ b/.github/spacy_universe_alert.py
@@ -0,0 +1,67 @@
+import os
+import sys
+import json
+from datetime import datetime
+
+from slack_sdk.web.client import WebClient
+
+CHANNEL = "#alerts-universe"
+SLACK_TOKEN = os.environ.get("SLACK_BOT_TOKEN", "ENV VAR not available!")
+DATETIME_FORMAT = "%Y-%m-%dT%H:%M:%SZ"
+
+client = WebClient(SLACK_TOKEN)
+github_context = json.loads(sys.argv[1])
+
+event = github_context['event']
+pr_title = event['pull_request']["title"]
+pr_link = event['pull_request']["patch_url"].replace(".patch", "")
+pr_author_url = event['sender']["html_url"]
+pr_author_name = pr_author_url.rsplit('/')[-1]
+pr_created_at_dt = datetime.strptime(
+ event['pull_request']["created_at"],
+ DATETIME_FORMAT
+)
+pr_created_at = pr_created_at_dt.strftime("%c")
+pr_updated_at_dt = datetime.strptime(
+ event['pull_request']["updated_at"],
+ DATETIME_FORMAT
+)
+pr_updated_at = pr_updated_at_dt.strftime("%c")
+
+blocks = [
+ {
+ "type": "section",
+ "text": {
+ "type": "mrkdwn",
+ "text": "📣 New spaCy Universe Project Alert ✨"
+ }
+ },
+ {
+ "type": "section",
+ "fields": [
+ {
+ "type": "mrkdwn",
+ "text": f"*Pull Request:*\n<{pr_link}|{pr_title}>"
+ },
+ {
+ "type": "mrkdwn",
+ "text": f"*Author:*\n<{pr_author_url}|{pr_author_name}>"
+ },
+ {
+ "type": "mrkdwn",
+ "text": f"*Created at:*\n {pr_created_at}"
+ },
+ {
+ "type": "mrkdwn",
+ "text": f"*Last Updated:*\n {pr_updated_at}"
+ }
+ ]
+ }
+ ]
+
+
+client.chat_postMessage(
+ channel=CHANNEL,
+ text="spaCy universe project PR alert",
+ blocks=blocks
+)
diff --git a/.github/workflows/autoblack.yml b/.github/workflows/autoblack.yml
index 8d0282650..70882c3cc 100644
--- a/.github/workflows/autoblack.yml
+++ b/.github/workflows/autoblack.yml
@@ -12,10 +12,10 @@ jobs:
if: github.repository_owner == 'explosion'
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v2
+ - uses: actions/checkout@v3
with:
ref: ${{ github.head_ref }}
- - uses: actions/setup-python@v2
+ - uses: actions/setup-python@v4
- run: pip install black
- name: Auto-format code if needed
run: black spacy
@@ -23,10 +23,11 @@ jobs:
# code and makes GitHub think the action failed
- name: Check for modified files
id: git-check
- run: echo ::set-output name=modified::$(if git diff-index --quiet HEAD --; then echo "false"; else echo "true"; fi)
+ run: echo modified=$(if git diff-index --quiet HEAD --; then echo "false"; else echo "true"; fi) >> $GITHUB_OUTPUT
+
- name: Create Pull Request
if: steps.git-check.outputs.modified == 'true'
- uses: peter-evans/create-pull-request@v3
+ uses: peter-evans/create-pull-request@v4
with:
title: Auto-format code with black
labels: meta
diff --git a/.github/workflows/explosionbot.yml b/.github/workflows/explosionbot.yml
index e29ce8fe8..6b472cd12 100644
--- a/.github/workflows/explosionbot.yml
+++ b/.github/workflows/explosionbot.yml
@@ -8,14 +8,14 @@ on:
jobs:
explosion-bot:
- runs-on: ubuntu-18.04
+ runs-on: ubuntu-latest
steps:
- name: Dump GitHub context
env:
GITHUB_CONTEXT: ${{ toJson(github) }}
run: echo "$GITHUB_CONTEXT"
- - uses: actions/checkout@v1
- - uses: actions/setup-python@v1
+ - uses: actions/checkout@v3
+ - uses: actions/setup-python@v4
- name: Install and run explosion-bot
run: |
pip install git+https://${{ secrets.EXPLOSIONBOT_TOKEN }}@github.com/explosion/explosion-bot
@@ -23,5 +23,5 @@ jobs:
env:
INPUT_TOKEN: ${{ secrets.EXPLOSIONBOT_TOKEN }}
INPUT_BK_TOKEN: ${{ secrets.BUILDKITE_SECRET }}
- ENABLED_COMMANDS: "test_gpu,test_slow"
+ ENABLED_COMMANDS: "test_gpu,test_slow,test_slow_gpu"
ALLOWED_TEAMS: "spaCy"
diff --git a/.github/workflows/gputests.yml b/.github/workflows/gputests.yml
index bb7f51d29..66e0707e0 100644
--- a/.github/workflows/gputests.yml
+++ b/.github/workflows/gputests.yml
@@ -10,6 +10,7 @@ jobs:
fail-fast: false
matrix:
branch: [master, v4]
+ if: github.repository_owner == 'explosion'
runs-on: ubuntu-latest
steps:
- name: Trigger buildkite build
diff --git a/.github/workflows/issue-manager.yml b/.github/workflows/issue-manager.yml
index 3fb42ed01..8f3a151ea 100644
--- a/.github/workflows/issue-manager.yml
+++ b/.github/workflows/issue-manager.yml
@@ -15,7 +15,7 @@ jobs:
issue-manager:
runs-on: ubuntu-latest
steps:
- - uses: tiangolo/issue-manager@0.2.1
+ - uses: tiangolo/issue-manager@0.4.0
with:
token: ${{ secrets.GITHUB_TOKEN }}
config: >
@@ -25,5 +25,11 @@ jobs:
"message": "This issue has been automatically closed because it was answered and there was no follow-up discussion.",
"remove_label_on_comment": true,
"remove_label_on_close": true
+ },
+ "more-info-needed": {
+ "delay": "P7D",
+ "message": "This issue has been automatically closed because there has been no response to a request for more information from the original author. With only the information that is currently in the issue, there's not enough information to take action. If you're the original author, feel free to reopen the issue if you have or find the answers needed to investigate further.",
+ "remove_label_on_comment": true,
+ "remove_label_on_close": true
}
}
diff --git a/.github/workflows/lock.yml b/.github/workflows/lock.yml
index c9833cdba..794adee85 100644
--- a/.github/workflows/lock.yml
+++ b/.github/workflows/lock.yml
@@ -15,11 +15,11 @@ jobs:
action:
runs-on: ubuntu-latest
steps:
- - uses: dessant/lock-threads@v3
+ - uses: dessant/lock-threads@v4
with:
process-only: 'issues'
issue-inactive-days: '30'
- issue-comment: >
- This thread has been automatically locked since there
- has not been any recent activity after it was closed.
+ issue-comment: >
+ This thread has been automatically locked since there
+ has not been any recent activity after it was closed.
Please open a new issue for related bugs.
diff --git a/.github/workflows/slowtests.yml b/.github/workflows/slowtests.yml
index 1a99c751c..f9fd3e817 100644
--- a/.github/workflows/slowtests.yml
+++ b/.github/workflows/slowtests.yml
@@ -10,10 +10,11 @@ jobs:
fail-fast: false
matrix:
branch: [master, v4]
+ if: github.repository_owner == 'explosion'
runs-on: ubuntu-latest
steps:
- name: Checkout
- uses: actions/checkout@v1
+ uses: actions/checkout@v3
with:
ref: ${{ matrix.branch }}
- name: Get commits from past 24 hours
@@ -22,9 +23,9 @@ jobs:
today=$(date '+%Y-%m-%d %H:%M:%S')
yesterday=$(date -d "yesterday" '+%Y-%m-%d %H:%M:%S')
if git log --after="$yesterday" --before="$today" | grep commit ; then
- echo "::set-output name=run_tests::true"
+ echo run_tests=true >> $GITHUB_OUTPUT
else
- echo "::set-output name=run_tests::false"
+ echo run_tests=false >> $GITHUB_OUTPUT
fi
- name: Trigger buildkite build
diff --git a/.github/workflows/spacy_universe_alert.yml b/.github/workflows/spacy_universe_alert.yml
new file mode 100644
index 000000000..837aaeb33
--- /dev/null
+++ b/.github/workflows/spacy_universe_alert.yml
@@ -0,0 +1,32 @@
+name: spaCy universe project alert
+
+on:
+ pull_request_target:
+ paths:
+ - "website/meta/universe.json"
+
+jobs:
+ build:
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Dump GitHub context
+ env:
+ GITHUB_CONTEXT: ${{ toJson(github) }}
+ PR_NUMBER: ${{github.event.number}}
+ run: |
+ echo "$GITHUB_CONTEXT"
+
+ - uses: actions/checkout@v3
+ - uses: actions/setup-python@v4
+ with:
+ python-version: '3.10'
+ - name: Install Bernadette app dependency and send an alert
+ env:
+ SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
+ GITHUB_CONTEXT: ${{ toJson(github) }}
+ CHANNEL: "#alerts-universe"
+ run: |
+ pip install slack-sdk==3.17.2 aiohttp==3.8.1
+ echo "$CHANNEL"
+ python .github/spacy_universe_alert.py "$GITHUB_CONTEXT"
diff --git a/.gitignore b/.gitignore
index ac72f2bbf..af75a4d47 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,20 +10,11 @@ spacy/tests/package/setup.cfg
spacy/tests/package/pyproject.toml
spacy/tests/package/requirements.txt
-# Website
-website/.cache/
-website/public/
-website/node_modules
-website/.npm
-website/logs
-*.log
-npm-debug.log*
-quickstart-training-generator.js
-
# Cython / C extensions
cythonize.json
spacy/*.html
*.cpp
+*.c
*.so
# Vim / VSCode / editors
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index a7a12fd24..e2c5e98fd 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -1,11 +1,12 @@
repos:
- repo: https://github.com/ambv/black
- rev: 21.6b0
+ rev: 22.3.0
hooks:
- id: black
language_version: python3.7
-- repo: https://gitlab.com/pycqa/flake8
- rev: 3.9.2
+ additional_dependencies: ['click==8.0.4']
+- repo: https://github.com/pycqa/flake8
+ rev: 5.0.4
hooks:
- id: flake8
args:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9a7d0744a..1f396bd71 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -144,7 +144,7 @@ Changes to `.py` files will be effective immediately.
When fixing a bug, first create an
[issue](https://github.com/explosion/spaCy/issues) if one does not already
-exist. The description text can be very short – we don't want to make this too
+exist. The description text can be very short – we don't want to make this too
bureaucratic.
Next, add a test to the relevant file in the
@@ -233,7 +233,7 @@ also want to keep an eye on unused declared variables or repeated
(i.e. overwritten) dictionary keys. If your code was formatted with `black`
(see above), you shouldn't see any formatting-related warnings.
-The [`.flake8`](.flake8) config defines the configuration we use for this
+The `flake8` section in [`setup.cfg`](setup.cfg) defines the configuration we use for this
codebase. For example, we're not super strict about the line length, and we're
excluding very large files like lemmatization and tokenizer exception tables.
@@ -271,7 +271,8 @@ except: # noqa: E722
### Python conventions
-All Python code must be written **compatible with Python 3.6+**.
+All Python code must be written **compatible with Python 3.6+**. More detailed
+code conventions can be found in the [developer docs](https://github.com/explosion/spaCy/blob/master/extra/DEVELOPER_DOCS/Code%20Conventions.md).
#### I/O and handling paths
diff --git a/MANIFEST.in b/MANIFEST.in
index b7826e456..8ded6f808 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,4 +1,4 @@
-recursive-include spacy *.pyi *.pyx *.pxd *.txt *.cfg *.jinja *.toml
+recursive-include spacy *.pyi *.pyx *.pxd *.txt *.cfg *.jinja *.toml *.hh
include LICENSE
include README.md
include pyproject.toml
diff --git a/README.md b/README.md
index 05c912ffa..49aa6796e 100644
--- a/README.md
+++ b/README.md
@@ -8,15 +8,15 @@ be used in real products.
spaCy comes with
[pretrained pipelines](https://spacy.io/models) and
-currently supports tokenization and training for **60+ languages**. It features
+currently supports tokenization and training for **70+ languages**. It features
state-of-the-art speed and **neural network models** for tagging,
parsing, **named entity recognition**, **text classification** and more,
multi-task learning with pretrained **transformers** like BERT, as well as a
production-ready [**training system**](https://spacy.io/usage/training) and easy
model packaging, deployment and workflow management. spaCy is commercial
-open-source software, released under the MIT license.
+open-source software, released under the [MIT license](https://github.com/explosion/spaCy/blob/master/LICENSE).
-💫 **Version 3.2 out now!**
+💫 **Version 3.5 out now!**
[Check out the release notes here.](https://github.com/explosion/spaCy/releases)
[](https://dev.azure.com/explosion-ai/public/_build?definitionId=8)
@@ -46,6 +46,7 @@ open-source software, released under the MIT license.
| 🛠 **[Changelog]** | Changes and version history. |
| 💝 **[Contribute]** | How to contribute to the spaCy project and code base. |
| | Get a custom spaCy pipeline, tailor-made for your NLP problem by spaCy's core developers. Streamlined, production-ready, predictable and maintainable. Start by completing our 5-minute questionnaire to tell us what you need and we'll be in touch! **[Learn more →](https://explosion.ai/spacy-tailored-pipelines)** |
+| | Bespoke advice for problem solving, strategy and analysis for applied NLP projects. Services include data strategy, code reviews, pipeline design and annotation coaching. Curious? Fill in our 5-minute questionnaire to tell us what you need and we'll be in touch! **[Learn more →](https://explosion.ai/spacy-tailored-analysis)** |
[spacy 101]: https://spacy.io/usage/spacy-101
[new in v3.0]: https://spacy.io/usage/v3
@@ -59,6 +60,7 @@ open-source software, released under the MIT license.
[changelog]: https://spacy.io/usage#changelog
[contribute]: https://github.com/explosion/spaCy/blob/master/CONTRIBUTING.md
+
## 💬 Where to ask questions
The spaCy project is maintained by the [spaCy team](https://explosion.ai/about).
@@ -79,7 +81,7 @@ more people can benefit from it.
## Features
-- Support for **60+ languages**
+- Support for **70+ languages**
- **Trained pipelines** for different languages and tasks
- Multi-task learning with pretrained **transformers** like BERT
- Support for pretrained **word vectors** and embeddings
diff --git a/azure-pipelines.yml b/azure-pipelines.yml
index 4624b2eb2..0f7ea91f9 100644
--- a/azure-pipelines.yml
+++ b/azure-pipelines.yml
@@ -31,8 +31,8 @@ jobs:
inputs:
versionSpec: "3.7"
- script: |
- pip install flake8==3.9.2
- python -m flake8 spacy --count --select=E901,E999,F821,F822,F823 --show-source --statistics
+ pip install flake8==5.0.4
+ python -m flake8 spacy --count --select=E901,E999,F821,F822,F823,W605 --show-source --statistics
displayName: "flake8"
- job: "Test"
@@ -41,7 +41,7 @@ jobs:
matrix:
# We're only running one platform per Python version to speed up builds
Python36Linux:
- imageName: "ubuntu-latest"
+ imageName: "ubuntu-20.04"
python.version: "3.6"
# Python36Windows:
# imageName: "windows-latest"
@@ -50,7 +50,7 @@ jobs:
# imageName: "macos-latest"
# python.version: "3.6"
# Python37Linux:
- # imageName: "ubuntu-latest"
+ # imageName: "ubuntu-20.04"
# python.version: "3.7"
Python37Windows:
imageName: "windows-latest"
@@ -76,15 +76,24 @@ jobs:
# Python39Mac:
# imageName: "macos-latest"
# python.version: "3.9"
- Python310Linux:
- imageName: "ubuntu-latest"
- python.version: "3.10"
+ # Python310Linux:
+ # imageName: "ubuntu-latest"
+ # python.version: "3.10"
Python310Windows:
imageName: "windows-latest"
python.version: "3.10"
- Python310Mac:
- imageName: "macos-latest"
- python.version: "3.10"
+ # Python310Mac:
+ # imageName: "macos-latest"
+ # python.version: "3.10"
+ Python311Linux:
+ imageName: 'ubuntu-latest'
+ python.version: '3.11'
+ Python311Windows:
+ imageName: 'windows-latest'
+ python.version: '3.11'
+ Python311Mac:
+ imageName: 'macos-latest'
+ python.version: '3.11'
maxParallel: 4
pool:
vmImage: $(imageName)
@@ -92,20 +101,3 @@ jobs:
- template: .github/azure-steps.yml
parameters:
python_version: '$(python.version)'
- architecture: 'x64'
-
-# - job: "TestGPU"
-# dependsOn: "Validate"
-# strategy:
-# matrix:
-# Python38LinuxX64_GPU:
-# python.version: '3.8'
-# pool:
-# name: "LinuxX64_GPU"
-# steps:
-# - template: .github/azure-steps.yml
-# parameters:
-# python_version: '$(python.version)'
-# architecture: 'x64'
-# gpu: true
-# num_build_jobs: 24
diff --git a/build-constraints.txt b/build-constraints.txt
index cf5fe3284..c1e82f1b0 100644
--- a/build-constraints.txt
+++ b/build-constraints.txt
@@ -1,6 +1,9 @@
# build version constraints for use with wheelwright + multibuild
-numpy==1.15.0; python_version<='3.7'
-numpy==1.17.3; python_version=='3.8'
+numpy==1.15.0; python_version<='3.7' and platform_machine!='aarch64'
+numpy==1.19.2; python_version<='3.7' and platform_machine=='aarch64'
+numpy==1.17.3; python_version=='3.8' and platform_machine!='aarch64'
+numpy==1.19.2; python_version=='3.8' and platform_machine=='aarch64'
numpy==1.19.3; python_version=='3.9'
numpy==1.21.3; python_version=='3.10'
-numpy; python_version>='3.11'
+numpy==1.23.2; python_version=='3.11'
+numpy; python_version>='3.12'
diff --git a/extra/DEVELOPER_DOCS/Code Conventions.md b/extra/DEVELOPER_DOCS/Code Conventions.md
index eba466c46..7294ac38b 100644
--- a/extra/DEVELOPER_DOCS/Code Conventions.md
+++ b/extra/DEVELOPER_DOCS/Code Conventions.md
@@ -137,7 +137,7 @@ If any of the TODOs you've added are important and should be fixed soon, you sho
## Type hints
-We use Python type hints across the `.py` files wherever possible. This makes it easy to understand what a function expects and returns, and modern editors will be able to show this information to you when you call an annotated function. Type hints are not currently used in the `.pyx` (Cython) code, except for definitions of registered functions and component factories, where they're used for config validation.
+We use Python type hints across the `.py` files wherever possible. This makes it easy to understand what a function expects and returns, and modern editors will be able to show this information to you when you call an annotated function. Type hints are not currently used in the `.pyx` (Cython) code, except for definitions of registered functions and component factories, where they're used for config validation. Ideally when developing, run `mypy spacy` on the code base to inspect any issues.
If possible, you should always use the more descriptive type hints like `List[str]` or even `List[Any]` instead of only `list`. We also annotate arguments and return types of `Callable` – although, you can simplify this if the type otherwise gets too verbose (e.g. functions that return factories to create callbacks). Remember that `Callable` takes two values: a **list** of the argument type(s) in order, and the return values.
@@ -155,6 +155,13 @@ def create_callback(some_arg: bool) -> Callable[[str, int], List[str]]:
return callback
```
+For typing variables, we prefer the explicit format.
+
+```diff
+- var = value # type: Type
++ var: Type = value
+```
+
For model architectures, Thinc also provides a collection of [custom types](https://thinc.ai/docs/api-types), including more specific types for arrays and model inputs/outputs. Even outside of static type checking, using these types will make the code a lot easier to read and follow, since it's always clear what array types are expected (and what might go wrong if the output is different from the expected type).
```python
@@ -184,6 +191,8 @@ def load_model(name: str) -> "Language":
...
```
+Note that we typically put the `from typing` import statements on the first line(s) of the Python module.
+
## Structuring logic
### Positional and keyword arguments
@@ -268,6 +277,27 @@ If you have to use `try`/`except`, make sure to only include what's **absolutely
+ return [v.strip() for v in value.split(",")]
```
+### Numeric comparisons
+
+For numeric comparisons, as a general rule we always use `<` and `>=` and avoid the usage of `<=` and `>`. This is to ensure we consistently
+apply inclusive lower bounds and exclusive upper bounds, helping to prevent off-by-one errors.
+
+One exception to this rule is the ternary case. With a chain like
+
+```python
+if value >= 0 and value < max:
+ ...
+```
+
+it's fine to rewrite this to the shorter form
+
+```python
+if 0 <= value < max:
+ ...
+```
+
+even though this requires the usage of the `<=` operator.
+
### Iteration and comprehensions
We generally avoid using built-in functions like `filter` or `map` in favor of list or generator comprehensions.
@@ -444,10 +474,14 @@ spaCy uses the [`pytest`](http://doc.pytest.org/) framework for testing. Tests f
When adding tests, make sure to use descriptive names and only test for one behavior at a time. Tests should be grouped into modules dedicated to the same type of functionality and some test modules are organized as directories of test files related to the same larger area of the library, e.g. `matcher` or `tokenizer`.
-Regression tests are tests that refer to bugs reported in specific issues. They should live in the relevant module of the test suite, named according to the issue number (e.g., `test_issue1234.py`), and [marked](https://docs.pytest.org/en/6.2.x/example/markers.html#working-with-custom-markers) appropriately (e.g. `@pytest.mark.issue(1234)`). This system allows us to relate tests for specific bugs back to the original reported issue, which is especially useful if we introduce a regression and a previously passing regression tests suddenly fails again. When fixing a bug, it's often useful to create a regression test for it first.
+Regression tests are tests that refer to bugs reported in specific issues. They should live in the relevant module of the test suite, named according to the issue number (e.g., `test_issue1234.py`), and [marked](https://docs.pytest.org/en/6.2.x/example/markers.html#working-with-custom-markers) appropriately (e.g. `@pytest.mark.issue(1234)`). This system allows us to relate tests for specific bugs back to the original reported issue, which is especially useful if we introduce a regression and a previously passing regression tests suddenly fails again. When fixing a bug, it's often useful to create a regression test for it first.
The test suite also provides [fixtures](https://github.com/explosion/spaCy/blob/master/spacy/tests/conftest.py) for different language tokenizers that can be used as function arguments of the same name and will be passed in automatically. Those should only be used for tests related to those specific languages. We also have [test utility functions](https://github.com/explosion/spaCy/blob/master/spacy/tests/util.py) for common operations, like creating a temporary file.
+### Testing Cython Code
+
+If you're developing Cython code (`.pyx` files), those extensions will need to be built before the test runner can test that code - otherwise it's going to run the tests with stale code from the last time the extension was built. You can build the extensions locally with `python setup.py build_ext -i`.
+
### Constructing objects and state
Test functions usually follow the same simple structure: they set up some state, perform the operation you want to test and `assert` conditions that you expect to be true, usually before and after the operation.
diff --git a/extra/DEVELOPER_DOCS/ExplosionBot.md b/extra/DEVELOPER_DOCS/ExplosionBot.md
new file mode 100644
index 000000000..606fe93a0
--- /dev/null
+++ b/extra/DEVELOPER_DOCS/ExplosionBot.md
@@ -0,0 +1,56 @@
+# Explosion-bot
+
+Explosion-bot is a robot that can be invoked to help with running particular test commands.
+
+## Permissions
+
+Only maintainers have permissions to summon explosion-bot. Each of the open source repos that use explosion-bot has its own team(s) of maintainers, and only github users who are members of those teams can successfully run bot commands.
+
+## Running robot commands
+
+To summon the robot, write a github comment on the issue/PR you wish to test. The comment must be in the following format:
+
+```
+@explosion-bot please test_gpu
+```
+
+Some things to note:
+
+- The `@explosion-bot please` must be the beginning of the command - you cannot add anything in front of this or else the robot won't know how to parse it. Adding anything at the end aside from the test name will also confuse the robot, so keep it simple!
+- The command name (such as `test_gpu`) must be one of the tests that the bot knows how to run. The available commands are documented in the bot's [workflow config](https://github.com/explosion/spaCy/blob/master/.github/workflows/explosionbot.yml#L26) and must match exactly one of the commands listed there.
+- The robot can't do multiple things at once, so if you want it to run multiple tests, you'll have to summon it with one comment per test.
+
+### Examples
+
+- Execute spaCy slow GPU tests with a custom thinc branch from a spaCy PR:
+
+ ```
+ @explosion-bot please test_slow_gpu --thinc-branch
+ ```
+
+ `branch_name` can either be a named branch, e.g: `develop`, or an unmerged PR, e.g: `refs/pull//head`.
+
+- Execute spaCy Transformers GPU tests from a spaCy PR:
+
+ ```
+ @explosion-bot please test_gpu --run-on spacy-transformers --run-on-branch master --spacy-branch current_pr
+ ```
+
+ This will launch the GPU pipeline for the `spacy-transformers` repo on its `master` branch, using the current spaCy PR's branch to build spaCy. The name of the repository passed to `--run-on` is case-sensitive, e.g: use `spaCy` instead of `spacy`.
+
+- General info about supported commands.
+
+ ```
+ @explosion-bot please info
+ ```
+
+- Help text for a specific command
+ ```
+ @explosion-bot please --help
+ ```
+
+## Troubleshooting
+
+If the robot isn't responding to commands as expected, you can check its logs in the [Github Action](https://github.com/explosion/spaCy/actions/workflows/explosionbot.yml).
+
+For each command sent to the bot, there should be a run of the `explosion-bot` workflow. In the `Install and run explosion-bot` step, towards the ends of the logs you should see info about the configuration that the bot was run with, as well as any errors that the bot encountered.
diff --git a/extra/DEVELOPER_DOCS/Satellite Packages.md b/extra/DEVELOPER_DOCS/Satellite Packages.md
new file mode 100644
index 000000000..02b06a90e
--- /dev/null
+++ b/extra/DEVELOPER_DOCS/Satellite Packages.md
@@ -0,0 +1,82 @@
+# spaCy Satellite Packages
+
+This is a list of all the active repos relevant to spaCy besides the main one, with short descriptions, history, and current status. Archived repos will not be covered.
+
+## Always Included in spaCy
+
+These packages are always pulled in when you install spaCy. Most of them are direct dependencies, but some are transitive dependencies through other packages.
+
+- [spacy-legacy](https://github.com/explosion/spacy-legacy): When an architecture in spaCy changes enough to get a new version, the old version is frozen and moved to spacy-legacy. This allows us to keep the core library slim while also preserving backwards compatability.
+- [thinc](https://github.com/explosion/thinc): Thinc is the machine learning library that powers trainable components in spaCy. It wraps backends like Numpy, PyTorch, and Tensorflow to provide a functional interface for specifying architectures.
+- [catalogue](https://github.com/explosion/catalogue): Small library for adding function registries, like those used for model architectures in spaCy.
+- [confection](https://github.com/explosion/confection): This library contains the functionality for config parsing that was formerly contained directly in Thinc.
+- [spacy-loggers](https://github.com/explosion/spacy-loggers): Contains loggers beyond the default logger available in spaCy's core code base. This includes loggers integrated with third-party services, which may differ in release cadence from spaCy itself.
+- [wasabi](https://github.com/explosion/wasabi): A command line formatting library, used for terminal output in spaCy.
+- [srsly](https://github.com/explosion/srsly): A wrapper that vendors several serialization libraries for spaCy. Includes parsers for JSON, JSONL, MessagePack, (extended) Pickle, and YAML.
+- [preshed](https://github.com/explosion/preshed): A Cython library for low-level data structures like hash maps, used for memory efficient data storage.
+- [cython-blis](https://github.com/explosion/cython-blis): Fast matrix multiplication using BLIS without depending on system libraries. Required by Thinc, rather than spaCy directly.
+- [murmurhash](https://github.com/explosion/murmurhash): A wrapper library for a C++ murmurhash implementation, used for string IDs in spaCy and preshed.
+- [cymem](https://github.com/explosion/cymem): A small library for RAII-style memory management in Cython.
+
+## Optional Extensions for spaCy
+
+These are repos that can be used by spaCy but aren't part of a default installation. Many of these are wrappers to integrate various kinds of third-party libraries.
+
+- [spacy-transformers](https://github.com/explosion/spacy-transformers): A wrapper for the [HuggingFace Transformers](https://huggingface.co/docs/transformers/index) library, this handles the extensive conversion necessary to coordinate spaCy's powerful `Doc` representation, training pipeline, and the Transformer embeddings. When released, this was known as `spacy-pytorch-transformers`, but it changed to the current name when HuggingFace update the name of their library as well.
+- [spacy-huggingface-hub](https://github.com/explosion/spacy-huggingface-hub): This package has a CLI script for uploading a packaged spaCy pipeline (created with `spacy package`) to the [Hugging Face Hub](https://huggingface.co/models).
+- [spacy-alignments](https://github.com/explosion/spacy-alignments): A wrapper for the tokenizations library (mentioned below) with a modified build system to simplify cross-platform wheel creation. Used in spacy-transformers for aligning spaCy and HuggingFace tokenizations.
+- [spacy-experimental](https://github.com/explosion/spacy-experimental): Experimental components that are not quite ready for inclusion in the main spaCy library. Usually there are unresolved questions around their APIs, so the experimental library allows us to expose them to the community for feedback before fully integrating them.
+- [spacy-lookups-data](https://github.com/explosion/spacy-lookups-data): A repository of linguistic data, such as lemmas, that takes up a lot of disk space. Originally created to reduce the size of the spaCy core library. This is mainly useful if you want the data included but aren't using a pretrained pipeline; for the affected languages, the relevant data is included in pretrained pipelines directly.
+- [coreferee](https://github.com/explosion/coreferee): Coreference resolution for English, French, German and Polish, optimised for limited training data and easily extensible for further languages. Used as a spaCy pipeline component.
+- [spacy-stanza](https://github.com/explosion/spacy-stanza): This is a wrapper that allows the use of Stanford's Stanza library in spaCy.
+- [spacy-streamlit](https://github.com/explosion/spacy-streamlit): A wrapper for the Streamlit dashboard building library to help with integrating [displaCy](https://spacy.io/api/top-level/#displacy).
+- [spacymoji](https://github.com/explosion/spacymoji): A library to add extra support for emoji to spaCy, such as including character names.
+- [thinc-apple-ops](https://github.com/explosion/thinc-apple-ops): A special backend for OSX that uses Apple's native libraries for improved performance.
+- [os-signpost](https://github.com/explosion/os-signpost): A Python package that allows you to use the `OSSignposter` API in OSX for performance analysis.
+- [spacy-ray](https://github.com/explosion/spacy-ray): A wrapper to integrate spaCy with Ray, a distributed training framework. Currently a work in progress.
+
+## Prodigy
+
+[Prodigy](https://prodi.gy) is Explosion's easy to use and highly customizable tool for annotating data. Prodigy itself requires a license, but the repos below contain documentation, examples, and editor or notebook integrations.
+
+- [prodigy-recipes](https://github.com/explosion/prodigy-recipes): Sample recipes for Prodigy, along with notebooks and other examples of usage.
+- [vscode-prodigy](https://github.com/explosion/vscode-prodigy): A VS Code extension that lets you run Prodigy inside VS Code.
+- [jupyterlab-prodigy](https://github.com/explosion/jupyterlab-prodigy): An extension for JupyterLab that lets you run Prodigy inside JupyterLab.
+
+## Independent Tools or Projects
+
+These are tools that may be related to or use spaCy, but are functional independent projects in their own right as well.
+
+- [floret](https://github.com/explosion/floret): A modification of fastText to use Bloom Embeddings. Can be used to add vectors with subword features to spaCy, and also works independently in the same manner as fastText.
+- [sense2vec](https://github.com/explosion/sense2vec): A library to make embeddings of noun phrases or words coupled with their part of speech. This library uses spaCy.
+- [spacy-vectors-builder](https://github.com/explosion/spacy-vectors-builder): This is a spaCy project that builds vectors using floret and a lot of input text. It handles downloading the input data as well as the actual building of vectors.
+- [holmes-extractor](https://github.com/explosion/holmes-extractor): Information extraction from English and German texts based on predicate logic. Uses spaCy.
+- [healthsea](https://github.com/explosion/healthsea): Healthsea is a project to extract information from comments about health supplements. Structurally, it's a self-contained, large spaCy project.
+- [spacy-pkuseg](https://github.com/explosion/spacy-pkuseg): A fork of the pkuseg Chinese tokenizer. Used for Chinese support in spaCy, but also works independently.
+- [ml-datasets](https://github.com/explosion/ml-datasets): This repo includes loaders for several standard machine learning datasets, like MNIST or WikiNER, and has historically been used in spaCy example code and documentation.
+
+## Documentation and Informational Repos
+
+These repos are used to support the spaCy docs or otherwise present information about spaCy or other Explosion projects.
+
+- [projects](https://github.com/explosion/projects): The projects repo is used to show detailed examples of spaCy usage. Individual projects can be checked out using the spaCy command line tool, rather than checking out the projects repo directly.
+- [spacy-course](https://github.com/explosion/spacy-course): Home to the interactive spaCy course for learning about how to use the library and some basic NLP principles.
+- [spacy-io-binder](https://github.com/explosion/spacy-io-binder): Home to the notebooks used for interactive examples in the documentation.
+
+## Organizational / Meta
+
+These repos are used for organizing data around spaCy, but are not something an end user would need to install as part of using the library.
+
+- [spacy-models](https://github.com/explosion/spacy-models): This repo contains metadata (but not training data) for all the spaCy models. This includes information about where their training data came from, version compatability, and performance information. It also includes tests for the model packages, and the built models are hosted as releases of this repo.
+- [wheelwright](https://github.com/explosion/wheelwright): A tool for automating our PyPI builds and releases.
+- [ec2buildwheel](https://github.com/explosion/ec2buildwheel): A small project that allows you to build Python packages in the manner of cibuildwheel, but on any EC2 image. Used by wheelwright.
+
+## Other
+
+Repos that don't fit in any of the above categories.
+
+- [blis](https://github.com/explosion/blis): A fork of the official BLIS library. The main branch is not updated, but work continues in various branches. This is used for cython-blis.
+- [tokenizations](https://github.com/explosion/tokenizations): A library originally by Yohei Tamura to align strings with tolerance to some variations in features like case and diacritics, used for aligning tokens and wordpieces. Adopted and maintained by Explosion, but usually spacy-alignments is used instead.
+- [conll-2012](https://github.com/explosion/conll-2012): A repo to hold some slightly cleaned up versions of the official scripts for the CoNLL 2012 shared task involving coreference resolution. Used in the coref project.
+- [fastapi-explosion-extras](https://github.com/explosion/fastapi-explosion-extras): Some small tweaks to FastAPI used at Explosion.
+
diff --git a/licenses/3rd_party_licenses.txt b/licenses/3rd_party_licenses.txt
index d58da9c4a..851e09585 100644
--- a/licenses/3rd_party_licenses.txt
+++ b/licenses/3rd_party_licenses.txt
@@ -127,3 +127,34 @@ distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
+
+
+polyleven
+---------
+
+* Files: spacy/matcher/polyleven.c
+
+MIT License
+
+Copyright (c) 2021 Fujimoto Seiji
+Copyright (c) 2021 Max Bachmann
+Copyright (c) 2022 Nick Mazuk
+Copyright (c) 2022 Michael Weiss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/pyproject.toml b/pyproject.toml
index f81484d43..7abd7a96f 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -5,9 +5,7 @@ requires = [
"cymem>=2.0.2,<2.1.0",
"preshed>=3.0.2,<3.1.0",
"murmurhash>=0.28.0,<1.1.0",
- "thinc>=8.0.12,<8.1.0",
- "blis>=0.4.0,<0.8.0",
- "pathy",
+ "thinc>=8.1.0,<8.2.0",
"numpy>=1.15.0",
]
build-backend = "setuptools.build_meta"
diff --git a/requirements.txt b/requirements.txt
index f3cb67bd9..1bd4518af 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,38 +1,40 @@
# Our libraries
-spacy-legacy>=3.0.8,<3.1.0
+spacy-legacy>=3.0.11,<3.1.0
spacy-loggers>=1.0.0,<2.0.0
cymem>=2.0.2,<2.1.0
preshed>=3.0.2,<3.1.0
-thinc>=8.0.12,<8.1.0
-blis>=0.4.0,<0.8.0
+thinc>=8.1.0,<8.2.0
ml_datasets>=0.2.0,<0.3.0
murmurhash>=0.28.0,<1.1.0
-wasabi>=0.9.0,<1.1.0
-srsly>=2.4.1,<3.0.0
+wasabi>=0.9.1,<1.2.0
+srsly>=2.4.3,<3.0.0
catalogue>=2.0.6,<2.1.0
-typer>=0.3.0,<0.5.0
-pathy>=0.3.5
+typer>=0.3.0,<0.8.0
+pathy>=0.10.0
+smart-open>=5.2.1,<7.0.0
# Third party dependencies
numpy>=1.15.0
requests>=2.13.0,<3.0.0
tqdm>=4.38.0,<5.0.0
-pydantic>=1.7.4,!=1.8,!=1.8.1,<1.9.0
+pydantic>=1.7.4,!=1.8,!=1.8.1,<1.11.0
jinja2
langcodes>=3.2.0,<4.0.0
# Official Python utilities
setuptools
packaging>=20.0
-typing_extensions>=3.7.4.1,<4.0.0.0; python_version < "3.8"
+typing_extensions>=3.7.4.1,<4.5.0; python_version < "3.8"
# Development dependencies
pre-commit>=2.13.0
cython>=0.25,<3.0
-pytest>=5.2.0
+pytest>=5.2.0,!=7.1.0
pytest-timeout>=1.3.0,<2.0.0
mock>=2.0.0,<3.0.0
-flake8>=3.8.0,<3.10.0
+flake8>=3.8.0,<6.0.0
hypothesis>=3.27.0,<7.0.0
-mypy==0.910
+mypy>=0.990,<0.1000; platform_machine != "aarch64" and python_version >= "3.7"
types-dataclasses>=0.1.3; python_version < "3.7"
types-mock>=0.1.1
+types-setuptools>=57.0.0
types-requests
+types-setuptools>=57.0.0
black>=22.0,<23.0
diff --git a/setup.cfg b/setup.cfg
index 9a257f5f9..cddc5148c 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -22,6 +22,7 @@ classifiers =
Programming Language :: Python :: 3.8
Programming Language :: Python :: 3.9
Programming Language :: Python :: 3.10
+ Programming Language :: Python :: 3.11
Topic :: Scientific/Engineering
project_urls =
Release notes = https://github.com/explosion/spaCy/releases
@@ -38,31 +39,31 @@ setup_requires =
cymem>=2.0.2,<2.1.0
preshed>=3.0.2,<3.1.0
murmurhash>=0.28.0,<1.1.0
- thinc>=8.0.12,<8.1.0
+ thinc>=8.1.0,<8.2.0
install_requires =
# Our libraries
- spacy-legacy>=3.0.8,<3.1.0
+ spacy-legacy>=3.0.11,<3.1.0
spacy-loggers>=1.0.0,<2.0.0
murmurhash>=0.28.0,<1.1.0
cymem>=2.0.2,<2.1.0
preshed>=3.0.2,<3.1.0
- thinc>=8.0.12,<8.1.0
- blis>=0.4.0,<0.8.0
- wasabi>=0.9.0,<1.1.0
- srsly>=2.4.1,<3.0.0
+ thinc>=8.1.0,<8.2.0
+ wasabi>=0.9.1,<1.2.0
+ srsly>=2.4.3,<3.0.0
catalogue>=2.0.6,<2.1.0
- typer>=0.3.0,<0.5.0
- pathy>=0.3.5
# Third-party dependencies
+ typer>=0.3.0,<0.8.0
+ pathy>=0.10.0
+ smart-open>=5.2.1,<7.0.0
tqdm>=4.38.0,<5.0.0
numpy>=1.15.0
requests>=2.13.0,<3.0.0
- pydantic>=1.7.4,!=1.8,!=1.8.1,<1.9.0
+ pydantic>=1.7.4,!=1.8,!=1.8.1,<1.11.0
jinja2
# Official Python utilities
setuptools
packaging>=20.0
- typing_extensions>=3.7.4,<4.0.0.0; python_version < "3.8"
+ typing_extensions>=3.7.4.1,<4.5.0; python_version < "3.8"
langcodes>=3.2.0,<4.0.0
[options.entry_points]
@@ -73,45 +74,53 @@ console_scripts =
lookups =
spacy_lookups_data>=1.0.3,<1.1.0
transformers =
- spacy_transformers>=1.1.2,<1.2.0
+ spacy_transformers>=1.1.2,<1.3.0
ray =
spacy_ray>=0.1.0,<1.0.0
cuda =
- cupy>=5.0.0b4,<11.0.0
+ cupy>=5.0.0b4,<12.0.0
cuda80 =
- cupy-cuda80>=5.0.0b4,<11.0.0
+ cupy-cuda80>=5.0.0b4,<12.0.0
cuda90 =
- cupy-cuda90>=5.0.0b4,<11.0.0
+ cupy-cuda90>=5.0.0b4,<12.0.0
cuda91 =
- cupy-cuda91>=5.0.0b4,<11.0.0
+ cupy-cuda91>=5.0.0b4,<12.0.0
cuda92 =
- cupy-cuda92>=5.0.0b4,<11.0.0
+ cupy-cuda92>=5.0.0b4,<12.0.0
cuda100 =
- cupy-cuda100>=5.0.0b4,<11.0.0
+ cupy-cuda100>=5.0.0b4,<12.0.0
cuda101 =
- cupy-cuda101>=5.0.0b4,<11.0.0
+ cupy-cuda101>=5.0.0b4,<12.0.0
cuda102 =
- cupy-cuda102>=5.0.0b4,<11.0.0
+ cupy-cuda102>=5.0.0b4,<12.0.0
cuda110 =
- cupy-cuda110>=5.0.0b4,<11.0.0
+ cupy-cuda110>=5.0.0b4,<12.0.0
cuda111 =
- cupy-cuda111>=5.0.0b4,<11.0.0
+ cupy-cuda111>=5.0.0b4,<12.0.0
cuda112 =
- cupy-cuda112>=5.0.0b4,<11.0.0
+ cupy-cuda112>=5.0.0b4,<12.0.0
cuda113 =
- cupy-cuda113>=5.0.0b4,<11.0.0
+ cupy-cuda113>=5.0.0b4,<12.0.0
cuda114 =
- cupy-cuda114>=5.0.0b4,<11.0.0
+ cupy-cuda114>=5.0.0b4,<12.0.0
cuda115 =
- cupy-cuda115>=5.0.0b4,<11.0.0
+ cupy-cuda115>=5.0.0b4,<12.0.0
+cuda116 =
+ cupy-cuda116>=5.0.0b4,<12.0.0
+cuda117 =
+ cupy-cuda117>=5.0.0b4,<12.0.0
+cuda11x =
+ cupy-cuda11x>=11.0.0,<12.0.0
+cuda-autodetect =
+ cupy-wheel>=11.0.0,<12.0.0
apple =
- thinc-apple-ops>=0.0.4,<1.0.0
+ thinc-apple-ops>=0.1.0.dev0,<1.0.0
# Language tokenizers with external dependencies
ja =
sudachipy>=0.5.2,!=0.6.1
sudachidict_core>=20211220
ko =
- natto-py==0.9.0
+ natto-py>=0.9.0
th =
pythainlp>=2.0
diff --git a/setup.py b/setup.py
index fcc124a43..243554c7a 100755
--- a/setup.py
+++ b/setup.py
@@ -23,16 +23,20 @@ Options.docstrings = True
PACKAGES = find_packages()
MOD_NAMES = [
+ "spacy.training.alignment_array",
"spacy.training.example",
"spacy.parts_of_speech",
"spacy.strings",
"spacy.lexeme",
"spacy.vocab",
"spacy.attrs",
- "spacy.kb",
+ "spacy.kb.candidate",
+ "spacy.kb.kb",
+ "spacy.kb.kb_in_memory",
"spacy.ml.parser_model",
"spacy.morphology",
"spacy.pipeline.dep_parser",
+ "spacy.pipeline._edit_tree_internals.edit_trees",
"spacy.pipeline.morphologizer",
"spacy.pipeline.multitask",
"spacy.pipeline.ner",
@@ -124,6 +128,8 @@ class build_ext_options:
class build_ext_subclass(build_ext, build_ext_options):
def build_extensions(self):
+ if self.parallel is None and os.environ.get("SPACY_NUM_BUILD_JOBS") is not None:
+ self.parallel = int(os.environ.get("SPACY_NUM_BUILD_JOBS"))
build_ext_options.build_options(self)
build_ext.build_extensions(self)
@@ -201,10 +207,25 @@ def setup_package():
get_python_inc(plat_specific=True),
]
ext_modules = []
+ ext_modules.append(
+ Extension(
+ "spacy.matcher.levenshtein",
+ [
+ "spacy/matcher/levenshtein.pyx",
+ "spacy/matcher/polyleven.c",
+ ],
+ language="c",
+ include_dirs=include_dirs,
+ )
+ )
for name in MOD_NAMES:
mod_path = name.replace(".", "/") + ".pyx"
ext = Extension(
- name, [mod_path], language="c++", include_dirs=include_dirs, extra_compile_args=["-std=c++11"]
+ name,
+ [mod_path],
+ language="c++",
+ include_dirs=include_dirs,
+ extra_compile_args=["-std=c++11"],
)
ext_modules.append(ext)
print("Cythonizing sources")
diff --git a/spacy/__init__.py b/spacy/__init__.py
index ca47edc94..c3568bc5c 100644
--- a/spacy/__init__.py
+++ b/spacy/__init__.py
@@ -31,25 +31,33 @@ def load(
name: Union[str, Path],
*,
vocab: Union[Vocab, bool] = True,
- disable: Iterable[str] = util.SimpleFrozenList(),
- exclude: Iterable[str] = util.SimpleFrozenList(),
+ disable: Union[str, Iterable[str]] = util._DEFAULT_EMPTY_PIPES,
+ enable: Union[str, Iterable[str]] = util._DEFAULT_EMPTY_PIPES,
+ exclude: Union[str, Iterable[str]] = util._DEFAULT_EMPTY_PIPES,
config: Union[Dict[str, Any], Config] = util.SimpleFrozenDict(),
) -> Language:
"""Load a spaCy model from an installed package or a local path.
name (str): Package name or model path.
vocab (Vocab): A Vocab object. If True, a vocab is created.
- disable (Iterable[str]): Names of pipeline components to disable. Disabled
+ disable (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to disable. Disabled
pipes will be loaded but they won't be run unless you explicitly
enable them by calling nlp.enable_pipe.
- exclude (Iterable[str]): Names of pipeline components to exclude. Excluded
+ enable (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to enable. All other
+ pipes will be disabled (but can be enabled later using nlp.enable_pipe).
+ exclude (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to exclude. Excluded
components won't be loaded.
config (Dict[str, Any] / Config): Config overrides as nested dict or dict
keyed by section values in dot notation.
RETURNS (Language): The loaded nlp object.
"""
return util.load_model(
- name, vocab=vocab, disable=disable, exclude=exclude, config=config
+ name,
+ vocab=vocab,
+ disable=disable,
+ enable=enable,
+ exclude=exclude,
+ config=config,
)
diff --git a/spacy/about.py b/spacy/about.py
index d01b278c9..640e9e93b 100644
--- a/spacy/about.py
+++ b/spacy/about.py
@@ -1,6 +1,6 @@
# fmt: off
__title__ = "spacy"
-__version__ = "3.2.2"
+__version__ = "3.5.0"
__download_url__ = "https://github.com/explosion/spacy-models/releases/download"
__compatibility__ = "https://raw.githubusercontent.com/explosion/spacy-models/master/compatibility.json"
__projects__ = "https://github.com/explosion/projects"
diff --git a/spacy/cli/__init__.py b/spacy/cli/__init__.py
index fd8da262e..868526b42 100644
--- a/spacy/cli/__init__.py
+++ b/spacy/cli/__init__.py
@@ -4,6 +4,7 @@ from ._util import app, setup_cli # noqa: F401
# These are the actual functions, NOT the wrapped CLI commands. The CLI commands
# are registered automatically and won't have to be imported here.
+from .benchmark_speed import benchmark_speed_cli # noqa: F401
from .download import download # noqa: F401
from .info import info # noqa: F401
from .package import package # noqa: F401
@@ -14,7 +15,9 @@ from .pretrain import pretrain # noqa: F401
from .debug_data import debug_data # noqa: F401
from .debug_config import debug_config # noqa: F401
from .debug_model import debug_model # noqa: F401
+from .debug_diff import debug_diff # noqa: F401
from .evaluate import evaluate # noqa: F401
+from .apply import apply # noqa: F401
from .convert import convert # noqa: F401
from .init_pipeline import init_pipeline_cli # noqa: F401
from .init_config import init_config, fill_config # noqa: F401
@@ -26,6 +29,7 @@ from .project.dvc import project_update_dvc # noqa: F401
from .project.push import project_push # noqa: F401
from .project.pull import project_pull # noqa: F401
from .project.document import project_document # noqa: F401
+from .find_threshold import find_threshold # noqa: F401
@app.command("link", no_args_is_help=True, deprecated=True, hidden=True)
diff --git a/spacy/cli/_util.py b/spacy/cli/_util.py
index fb680d888..ba3892b1d 100644
--- a/spacy/cli/_util.py
+++ b/spacy/cli/_util.py
@@ -12,7 +12,7 @@ from click.parser import split_arg_string
from typer.main import get_command
from contextlib import contextmanager
from thinc.api import Config, ConfigValidationError, require_gpu
-from thinc.util import has_cupy, gpu_is_available
+from thinc.util import gpu_is_available
from configparser import InterpolationError
import os
@@ -23,7 +23,7 @@ from ..util import is_compatible_version, SimpleFrozenDict, ENV_VARS
from .. import about
if TYPE_CHECKING:
- from pathy import Pathy # noqa: F401
+ from pathy import FluidPath # noqa: F401
SDIST_SUFFIX = ".tar.gz"
@@ -46,6 +46,7 @@ DEBUG_HELP = """Suite of helpful commands for debugging and profiling. Includes
commands to check and validate your config files, training and evaluation data,
and custom model implementations.
"""
+BENCHMARK_HELP = """Commands for benchmarking pipelines."""
INIT_HELP = """Commands for initializing configs and pipeline packages."""
# Wrappers for Typer's annotations. Initially created to set defaults and to
@@ -54,12 +55,14 @@ Arg = typer.Argument
Opt = typer.Option
app = typer.Typer(name=NAME, help=HELP)
+benchmark_cli = typer.Typer(name="benchmark", help=BENCHMARK_HELP, no_args_is_help=True)
project_cli = typer.Typer(name="project", help=PROJECT_HELP, no_args_is_help=True)
debug_cli = typer.Typer(name="debug", help=DEBUG_HELP, no_args_is_help=True)
init_cli = typer.Typer(name="init", help=INIT_HELP, no_args_is_help=True)
app.add_typer(project_cli)
app.add_typer(debug_cli)
+app.add_typer(benchmark_cli)
app.add_typer(init_cli)
@@ -158,15 +161,15 @@ def load_project_config(
sys.exit(1)
validate_project_version(config)
validate_project_commands(config)
+ if interpolate:
+ err = f"{PROJECT_FILE} validation error"
+ with show_validation_error(title=err, hint_fill=False):
+ config = substitute_project_variables(config, overrides)
# Make sure directories defined in config exist
for subdir in config.get("directories", []):
dir_path = path / subdir
if not dir_path.exists():
dir_path.mkdir(parents=True)
- if interpolate:
- err = f"{PROJECT_FILE} validation error"
- with show_validation_error(title=err, hint_fill=False):
- config = substitute_project_variables(config, overrides)
return config
@@ -331,7 +334,7 @@ def import_code(code_path: Optional[Union[Path, str]]) -> None:
msg.fail(f"Couldn't load Python code: {code_path}", e, exits=1)
-def upload_file(src: Path, dest: Union[str, "Pathy"]) -> None:
+def upload_file(src: Path, dest: Union[str, "FluidPath"]) -> None:
"""Upload a file.
src (Path): The source path.
@@ -339,13 +342,20 @@ def upload_file(src: Path, dest: Union[str, "Pathy"]) -> None:
"""
import smart_open
+ # Create parent directories for local paths
+ if isinstance(dest, Path):
+ if not dest.parent.exists():
+ dest.parent.mkdir(parents=True)
+
dest = str(dest)
with smart_open.open(dest, mode="wb") as output_file:
with src.open(mode="rb") as input_file:
output_file.write(input_file.read())
-def download_file(src: Union[str, "Pathy"], dest: Path, *, force: bool = False) -> None:
+def download_file(
+ src: Union[str, "FluidPath"], dest: Path, *, force: bool = False
+) -> None:
"""Download a file using smart_open.
url (str): The URL of the file.
@@ -358,9 +368,9 @@ def download_file(src: Union[str, "Pathy"], dest: Path, *, force: bool = False)
if dest.exists() and not force:
return None
src = str(src)
- with smart_open.open(src, mode="rb", ignore_ext=True) as input_file:
+ with smart_open.open(src, mode="rb", compression="disable") as input_file:
with dest.open(mode="wb") as output_file:
- output_file.write(input_file.read())
+ shutil.copyfileobj(input_file, output_file)
def ensure_pathy(path):
@@ -368,7 +378,7 @@ def ensure_pathy(path):
slow and annoying Google Cloud warning)."""
from pathy import Pathy # noqa: F811
- return Pathy(path)
+ return Pathy.fluid(path)
def git_checkout(
@@ -462,6 +472,23 @@ def git_sparse_checkout(repo, subpath, dest, branch):
shutil.move(str(source_path), str(dest))
+def git_repo_branch_exists(repo: str, branch: str) -> bool:
+ """Uses 'git ls-remote' to check if a repository and branch exists
+
+ repo (str): URL to get repo.
+ branch (str): Branch on repo to check.
+ RETURNS (bool): True if repo:branch exists.
+ """
+ get_git_version()
+ cmd = f"git ls-remote {repo} {branch}"
+ # We might be tempted to use `--exit-code` with `git ls-remote`, but
+ # `run_command` handles the `returncode` for us, so we'll rely on
+ # the fact that stdout returns '' if the requested branch doesn't exist
+ ret = run_command(cmd, capture=True)
+ exists = ret.stdout != ""
+ return exists
+
+
def get_git_version(
error: str = "Could not run 'git'. Make sure it's installed and the executable is available.",
) -> Tuple[int, int]:
@@ -554,5 +581,41 @@ def setup_gpu(use_gpu: int, silent=None) -> None:
require_gpu(use_gpu)
else:
local_msg.info("Using CPU")
- if has_cupy and gpu_is_available():
+ if gpu_is_available():
local_msg.info("To switch to GPU 0, use the option: --gpu-id 0")
+
+
+def walk_directory(path: Path, suffix: Optional[str] = None) -> List[Path]:
+ """Given a directory and a suffix, recursively find all files matching the suffix.
+ Directories or files with names beginning with a . are ignored, but hidden flags on
+ filesystems are not checked.
+ When provided with a suffix `None`, there is no suffix-based filtering."""
+ if not path.is_dir():
+ return [path]
+ paths = [path]
+ locs = []
+ seen = set()
+ for path in paths:
+ if str(path) in seen:
+ continue
+ seen.add(str(path))
+ if path.parts[-1].startswith("."):
+ continue
+ elif path.is_dir():
+ paths.extend(path.iterdir())
+ elif suffix is not None and not path.parts[-1].endswith(suffix):
+ continue
+ else:
+ locs.append(path)
+ # It's good to sort these, in case the ordering messes up cache.
+ locs.sort()
+ return locs
+
+
+def _format_number(number: Union[int, float], ndigits: int = 2) -> str:
+ """Formats a number (float or int) rounding to `ndigits`, without truncating trailing 0s,
+ as happens with `round(number, ndigits)`"""
+ if isinstance(number, float):
+ return f"{number:.{ndigits}f}"
+ else:
+ return str(number)
diff --git a/spacy/cli/apply.py b/spacy/cli/apply.py
new file mode 100644
index 000000000..f0df4e757
--- /dev/null
+++ b/spacy/cli/apply.py
@@ -0,0 +1,143 @@
+import tqdm
+import srsly
+
+from itertools import chain
+from pathlib import Path
+from typing import Optional, List, Iterable, cast, Union
+
+from wasabi import msg
+
+from ._util import app, Arg, Opt, setup_gpu, import_code, walk_directory
+
+from ..tokens import Doc, DocBin
+from ..vocab import Vocab
+from ..util import ensure_path, load_model
+
+
+path_help = """Location of the documents to predict on.
+Can be a single file in .spacy format or a .jsonl file.
+Files with other extensions are treated as single plain text documents.
+If a directory is provided it is traversed recursively to grab
+all files to be processed.
+The files can be a mixture of .spacy, .jsonl and text files.
+If .jsonl is provided the specified field is going
+to be grabbed ("text" by default)."""
+
+out_help = "Path to save the resulting .spacy file"
+code_help = (
+ "Path to Python file with additional " "code (registered functions) to be imported"
+)
+gold_help = "Use gold preprocessing provided in the .spacy files"
+force_msg = (
+ "The provided output file already exists. "
+ "To force overwriting the output file, set the --force or -F flag."
+)
+
+
+DocOrStrStream = Union[Iterable[str], Iterable[Doc]]
+
+
+def _stream_docbin(path: Path, vocab: Vocab) -> Iterable[Doc]:
+ """
+ Stream Doc objects from DocBin.
+ """
+ docbin = DocBin().from_disk(path)
+ for doc in docbin.get_docs(vocab):
+ yield doc
+
+
+def _stream_jsonl(path: Path, field: str) -> Iterable[str]:
+ """
+ Stream "text" field from JSONL. If the field "text" is
+ not found it raises error.
+ """
+ for entry in srsly.read_jsonl(path):
+ if field not in entry:
+ msg.fail(f"{path} does not contain the required '{field}' field.", exits=1)
+ else:
+ yield entry[field]
+
+
+def _stream_texts(paths: Iterable[Path]) -> Iterable[str]:
+ """
+ Yields strings from text files in paths.
+ """
+ for path in paths:
+ with open(path, "r") as fin:
+ text = fin.read()
+ yield text
+
+
+@app.command("apply")
+def apply_cli(
+ # fmt: off
+ model: str = Arg(..., help="Model name or path"),
+ data_path: Path = Arg(..., help=path_help, exists=True),
+ output_file: Path = Arg(..., help=out_help, dir_okay=False),
+ code_path: Optional[Path] = Opt(None, "--code", "-c", help=code_help),
+ text_key: str = Opt("text", "--text-key", "-tk", help="Key containing text string for JSONL"),
+ force_overwrite: bool = Opt(False, "--force", "-F", help="Force overwriting the output file"),
+ use_gpu: int = Opt(-1, "--gpu-id", "-g", help="GPU ID or -1 for CPU."),
+ batch_size: int = Opt(1, "--batch-size", "-b", help="Batch size."),
+ n_process: int = Opt(1, "--n-process", "-n", help="number of processors to use.")
+):
+ """
+ Apply a trained pipeline to documents to get predictions.
+ Expects a loadable spaCy pipeline and path to the data, which
+ can be a directory or a file.
+ The data files can be provided in multiple formats:
+ 1. .spacy files
+ 2. .jsonl files with a specified "field" to read the text from.
+ 3. Files with any other extension are assumed to be containing
+ a single document.
+ DOCS: https://spacy.io/api/cli#apply
+ """
+ data_path = ensure_path(data_path)
+ output_file = ensure_path(output_file)
+ code_path = ensure_path(code_path)
+ if output_file.exists() and not force_overwrite:
+ msg.fail(force_msg, exits=1)
+ if not data_path.exists():
+ msg.fail(f"Couldn't find data path: {data_path}", exits=1)
+ import_code(code_path)
+ setup_gpu(use_gpu)
+ apply(data_path, output_file, model, text_key, batch_size, n_process)
+
+
+def apply(
+ data_path: Path,
+ output_file: Path,
+ model: str,
+ json_field: str,
+ batch_size: int,
+ n_process: int,
+):
+ docbin = DocBin(store_user_data=True)
+ paths = walk_directory(data_path)
+ if len(paths) == 0:
+ docbin.to_disk(output_file)
+ msg.warn(
+ "Did not find data to process,"
+ f" {data_path} seems to be an empty directory."
+ )
+ return
+ nlp = load_model(model)
+ msg.good(f"Loaded model {model}")
+ vocab = nlp.vocab
+ streams: List[DocOrStrStream] = []
+ text_files = []
+ for path in paths:
+ if path.suffix == ".spacy":
+ streams.append(_stream_docbin(path, vocab))
+ elif path.suffix == ".jsonl":
+ streams.append(_stream_jsonl(path, json_field))
+ else:
+ text_files.append(path)
+ if len(text_files) > 0:
+ streams.append(_stream_texts(text_files))
+ datagen = cast(DocOrStrStream, chain(*streams))
+ for doc in tqdm.tqdm(nlp.pipe(datagen, batch_size=batch_size, n_process=n_process)):
+ docbin.add(doc)
+ if output_file.suffix == "":
+ output_file = output_file.with_suffix(".spacy")
+ docbin.to_disk(output_file)
diff --git a/spacy/cli/benchmark_speed.py b/spacy/cli/benchmark_speed.py
new file mode 100644
index 000000000..4eb20a5fa
--- /dev/null
+++ b/spacy/cli/benchmark_speed.py
@@ -0,0 +1,174 @@
+from typing import Iterable, List, Optional
+import random
+from itertools import islice
+import numpy
+from pathlib import Path
+import time
+from tqdm import tqdm
+import typer
+from wasabi import msg
+
+from .. import util
+from ..language import Language
+from ..tokens import Doc
+from ..training import Corpus
+from ._util import Arg, Opt, benchmark_cli, setup_gpu
+
+
+@benchmark_cli.command(
+ "speed",
+ context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+)
+def benchmark_speed_cli(
+ # fmt: off
+ ctx: typer.Context,
+ model: str = Arg(..., help="Model name or path"),
+ data_path: Path = Arg(..., help="Location of binary evaluation data in .spacy format", exists=True),
+ batch_size: Optional[int] = Opt(None, "--batch-size", "-b", min=1, help="Override the pipeline batch size"),
+ no_shuffle: bool = Opt(False, "--no-shuffle", help="Do not shuffle benchmark data"),
+ use_gpu: int = Opt(-1, "--gpu-id", "-g", help="GPU ID or -1 for CPU"),
+ n_batches: int = Opt(50, "--batches", help="Minimum number of batches to benchmark", min=30,),
+ warmup_epochs: int = Opt(3, "--warmup", "-w", min=0, help="Number of iterations over the data for warmup"),
+ # fmt: on
+):
+ """
+ Benchmark a pipeline. Expects a loadable spaCy pipeline and benchmark
+ data in the binary .spacy format.
+ """
+ setup_gpu(use_gpu=use_gpu, silent=False)
+
+ nlp = util.load_model(model)
+ batch_size = batch_size if batch_size is not None else nlp.batch_size
+ corpus = Corpus(data_path)
+ docs = [eg.predicted for eg in corpus(nlp)]
+
+ if len(docs) == 0:
+ msg.fail("Cannot benchmark speed using an empty corpus.", exits=1)
+
+ print(f"Warming up for {warmup_epochs} epochs...")
+ warmup(nlp, docs, warmup_epochs, batch_size)
+
+ print()
+ print(f"Benchmarking {n_batches} batches...")
+ wps = benchmark(nlp, docs, n_batches, batch_size, not no_shuffle)
+
+ print()
+ print_outliers(wps)
+ print_mean_with_ci(wps)
+
+
+# Lowercased, behaves as a context manager function.
+class time_context:
+ """Register the running time of a context."""
+
+ def __enter__(self):
+ self.start = time.perf_counter()
+ return self
+
+ def __exit__(self, type, value, traceback):
+ self.elapsed = time.perf_counter() - self.start
+
+
+class Quartiles:
+ """Calculate the q1, q2, q3 quartiles and the inter-quartile range (iqr)
+ of a sample."""
+
+ q1: float
+ q2: float
+ q3: float
+ iqr: float
+
+ def __init__(self, sample: numpy.ndarray) -> None:
+ self.q1 = numpy.quantile(sample, 0.25)
+ self.q2 = numpy.quantile(sample, 0.5)
+ self.q3 = numpy.quantile(sample, 0.75)
+ self.iqr = self.q3 - self.q1
+
+
+def annotate(
+ nlp: Language, docs: List[Doc], batch_size: Optional[int]
+) -> numpy.ndarray:
+ docs = nlp.pipe(tqdm(docs, unit="doc"), batch_size=batch_size)
+ wps = []
+ while True:
+ with time_context() as elapsed:
+ batch_docs = list(
+ islice(docs, batch_size if batch_size else nlp.batch_size)
+ )
+ if len(batch_docs) == 0:
+ break
+ n_tokens = count_tokens(batch_docs)
+ wps.append(n_tokens / elapsed.elapsed)
+
+ return numpy.array(wps)
+
+
+def benchmark(
+ nlp: Language,
+ docs: List[Doc],
+ n_batches: int,
+ batch_size: int,
+ shuffle: bool,
+) -> numpy.ndarray:
+ if shuffle:
+ bench_docs = [
+ nlp.make_doc(random.choice(docs).text)
+ for _ in range(n_batches * batch_size)
+ ]
+ else:
+ bench_docs = [
+ nlp.make_doc(docs[i % len(docs)].text)
+ for i in range(n_batches * batch_size)
+ ]
+
+ return annotate(nlp, bench_docs, batch_size)
+
+
+def bootstrap(x, statistic=numpy.mean, iterations=10000) -> numpy.ndarray:
+ """Apply a statistic to repeated random samples of an array."""
+ return numpy.fromiter(
+ (
+ statistic(numpy.random.choice(x, len(x), replace=True))
+ for _ in range(iterations)
+ ),
+ numpy.float64,
+ )
+
+
+def count_tokens(docs: Iterable[Doc]) -> int:
+ return sum(len(doc) for doc in docs)
+
+
+def print_mean_with_ci(sample: numpy.ndarray):
+ mean = numpy.mean(sample)
+ bootstrap_means = bootstrap(sample)
+ bootstrap_means.sort()
+
+ # 95% confidence interval
+ low = bootstrap_means[int(len(bootstrap_means) * 0.025)]
+ high = bootstrap_means[int(len(bootstrap_means) * 0.975)]
+
+ print(f"Mean: {mean:.1f} words/s (95% CI: {low-mean:.1f} +{high-mean:.1f})")
+
+
+def print_outliers(sample: numpy.ndarray):
+ quartiles = Quartiles(sample)
+
+ n_outliers = numpy.sum(
+ (sample < (quartiles.q1 - 1.5 * quartiles.iqr))
+ | (sample > (quartiles.q3 + 1.5 * quartiles.iqr))
+ )
+ n_extreme_outliers = numpy.sum(
+ (sample < (quartiles.q1 - 3.0 * quartiles.iqr))
+ | (sample > (quartiles.q3 + 3.0 * quartiles.iqr))
+ )
+ print(
+ f"Outliers: {(100 * n_outliers) / len(sample):.1f}%, extreme outliers: {(100 * n_extreme_outliers) / len(sample)}%"
+ )
+
+
+def warmup(
+ nlp: Language, docs: List[Doc], warmup_epochs: int, batch_size: Optional[int]
+) -> numpy.ndarray:
+ docs = warmup_epochs * docs
+ return annotate(nlp, docs, batch_size)
diff --git a/spacy/cli/convert.py b/spacy/cli/convert.py
index 04eb7078f..68d454b3e 100644
--- a/spacy/cli/convert.py
+++ b/spacy/cli/convert.py
@@ -1,4 +1,4 @@
-from typing import Callable, Iterable, Mapping, Optional, Any, List, Union
+from typing import Callable, Iterable, Mapping, Optional, Any, Union
from enum import Enum
from pathlib import Path
from wasabi import Printer
@@ -7,7 +7,7 @@ import re
import sys
import itertools
-from ._util import app, Arg, Opt
+from ._util import app, Arg, Opt, walk_directory
from ..training import docs_to_json
from ..tokens import Doc, DocBin
from ..training.converters import iob_to_docs, conll_ner_to_docs, json_to_docs
@@ -28,6 +28,8 @@ CONVERTERS: Mapping[str, Callable[..., Iterable[Doc]]] = {
"json": json_to_docs,
}
+AUTO = "auto"
+
# File types that can be written to stdout
FILE_TYPES_STDOUT = ("json",)
@@ -49,7 +51,7 @@ def convert_cli(
model: Optional[str] = Opt(None, "--model", "--base", "-b", help="Trained spaCy pipeline for sentence segmentation to use as base (for --seg-sents)"),
morphology: bool = Opt(False, "--morphology", "-m", help="Enable appending morphology to tags"),
merge_subtokens: bool = Opt(False, "--merge-subtokens", "-T", help="Merge CoNLL-U subtokens"),
- converter: str = Opt("auto", "--converter", "-c", help=f"Converter: {tuple(CONVERTERS.keys())}"),
+ converter: str = Opt(AUTO, "--converter", "-c", help=f"Converter: {tuple(CONVERTERS.keys())}"),
ner_map: Optional[Path] = Opt(None, "--ner-map", "-nm", help="NER tag mapping (as JSON-encoded dict of entity types)", exists=True),
lang: Optional[str] = Opt(None, "--lang", "-l", help="Language (if tokenizer required)"),
concatenate: bool = Opt(None, "--concatenate", "-C", help="Concatenate output to a single file"),
@@ -70,8 +72,8 @@ def convert_cli(
output_dir: Union[str, Path] = "-" if output_dir == Path("-") else output_dir
silent = output_dir == "-"
msg = Printer(no_print=silent)
- verify_cli_args(msg, input_path, output_dir, file_type.value, converter, ner_map)
converter = _get_converter(msg, converter, input_path)
+ verify_cli_args(msg, input_path, output_dir, file_type.value, converter, ner_map)
convert(
input_path,
output_dir,
@@ -100,7 +102,7 @@ def convert(
model: Optional[str] = None,
morphology: bool = False,
merge_subtokens: bool = False,
- converter: str = "auto",
+ converter: str,
ner_map: Optional[Path] = None,
lang: Optional[str] = None,
concatenate: bool = False,
@@ -189,33 +191,6 @@ def autodetect_ner_format(input_data: str) -> Optional[str]:
return None
-def walk_directory(path: Path, converter: str) -> List[Path]:
- if not path.is_dir():
- return [path]
- paths = [path]
- locs = []
- seen = set()
- for path in paths:
- if str(path) in seen:
- continue
- seen.add(str(path))
- if path.parts[-1].startswith("."):
- continue
- elif path.is_dir():
- paths.extend(path.iterdir())
- elif converter == "json" and not path.parts[-1].endswith("json"):
- continue
- elif converter == "conll" and not path.parts[-1].endswith("conll"):
- continue
- elif converter == "iob" and not path.parts[-1].endswith("iob"):
- continue
- else:
- locs.append(path)
- # It's good to sort these, in case the ordering messes up cache.
- locs.sort()
- return locs
-
-
def verify_cli_args(
msg: Printer,
input_path: Path,
@@ -239,18 +214,22 @@ def verify_cli_args(
input_locs = walk_directory(input_path, converter)
if len(input_locs) == 0:
msg.fail("No input files in directory", input_path, exits=1)
- file_types = list(set([loc.suffix[1:] for loc in input_locs]))
- if converter == "auto" and len(file_types) >= 2:
- file_types_str = ",".join(file_types)
- msg.fail("All input files must be same type", file_types_str, exits=1)
- if converter != "auto" and converter not in CONVERTERS:
+ if converter not in CONVERTERS:
msg.fail(f"Can't find converter for {converter}", exits=1)
def _get_converter(msg, converter, input_path: Path):
if input_path.is_dir():
- input_path = walk_directory(input_path, converter)[0]
- if converter == "auto":
+ if converter == AUTO:
+ input_locs = walk_directory(input_path, suffix=None)
+ file_types = list(set([loc.suffix[1:] for loc in input_locs]))
+ if len(file_types) >= 2:
+ file_types_str = ",".join(file_types)
+ msg.fail("All input files must be same type", file_types_str, exits=1)
+ input_path = input_locs[0]
+ else:
+ input_path = walk_directory(input_path, suffix=converter)[0]
+ if converter == AUTO:
converter = input_path.suffix[1:]
if converter == "ner" or converter == "iob":
with input_path.open(encoding="utf8") as file_:
diff --git a/spacy/cli/debug_data.py b/spacy/cli/debug_data.py
index a63795148..a85324e87 100644
--- a/spacy/cli/debug_data.py
+++ b/spacy/cli/debug_data.py
@@ -6,12 +6,14 @@ import sys
import srsly
from wasabi import Printer, MESSAGES, msg
import typer
+import math
from ._util import app, Arg, Opt, show_validation_error, parse_config_overrides
-from ._util import import_code, debug_cli
-from ..training import Example
+from ._util import import_code, debug_cli, _format_number
+from ..training import Example, remove_bilu_prefix
from ..training.initialize import get_sourced_components
from ..schemas import ConfigSchemaTraining
+from ..pipeline import TrainablePipe
from ..pipeline._parser_internals import nonproj
from ..pipeline._parser_internals.nonproj import DELIMITER
from ..pipeline import Morphologizer, SpanCategorizer
@@ -19,6 +21,7 @@ from ..morphology import Morphology
from ..language import Language
from ..util import registry, resolve_dot_names
from ..compat import Literal
+from ..vectors import Mode as VectorsMode
from .. import util
@@ -29,6 +32,12 @@ DEP_LABEL_THRESHOLD = 20
# Minimum number of expected examples to train a new pipeline
BLANK_MODEL_MIN_THRESHOLD = 100
BLANK_MODEL_THRESHOLD = 2000
+# Arbitrary threshold where SpanCat performs well
+SPAN_DISTINCT_THRESHOLD = 1
+# Arbitrary threshold where SpanCat performs well
+BOUNDARY_DISTINCT_THRESHOLD = 1
+# Arbitrary threshold for filtering span lengths during reporting (percentage)
+SPAN_LENGTH_THRESHOLD_PERCENTAGE = 90
@debug_cli.command(
@@ -170,26 +179,34 @@ def debug_data(
show=verbose,
)
if len(nlp.vocab.vectors):
- msg.info(
- f"{len(nlp.vocab.vectors)} vectors ({nlp.vocab.vectors.n_keys} "
- f"unique keys, {nlp.vocab.vectors_length} dimensions)"
- )
- n_missing_vectors = sum(gold_train_data["words_missing_vectors"].values())
- msg.warn(
- "{} words in training data without vectors ({:.0f}%)".format(
- n_missing_vectors,
- 100 * (n_missing_vectors / gold_train_data["n_words"]),
- ),
- )
- msg.text(
- "10 most common words without vectors: {}".format(
- _format_labels(
- gold_train_data["words_missing_vectors"].most_common(10),
- counts=True,
- )
- ),
- show=verbose,
- )
+ if nlp.vocab.vectors.mode == VectorsMode.floret:
+ msg.info(
+ f"floret vectors with {len(nlp.vocab.vectors)} vectors, "
+ f"{nlp.vocab.vectors_length} dimensions, "
+ f"{nlp.vocab.vectors.minn}-{nlp.vocab.vectors.maxn} char "
+ f"n-gram subwords"
+ )
+ else:
+ msg.info(
+ f"{len(nlp.vocab.vectors)} vectors ({nlp.vocab.vectors.n_keys} "
+ f"unique keys, {nlp.vocab.vectors_length} dimensions)"
+ )
+ n_missing_vectors = sum(gold_train_data["words_missing_vectors"].values())
+ msg.warn(
+ "{} words in training data without vectors ({:.0f}%)".format(
+ n_missing_vectors,
+ 100 * (n_missing_vectors / gold_train_data["n_words"]),
+ ),
+ )
+ msg.text(
+ "10 most common words without vectors: {}".format(
+ _format_labels(
+ gold_train_data["words_missing_vectors"].most_common(10),
+ counts=True,
+ )
+ ),
+ show=verbose,
+ )
else:
msg.info("No word vectors present in the package")
@@ -238,6 +255,69 @@ def debug_data(
msg.warn(f"No examples for texts WITHOUT new label '{label}'")
has_no_neg_warning = True
+ with msg.loading("Obtaining span characteristics..."):
+ span_characteristics = _get_span_characteristics(
+ train_dataset, gold_train_data, spans_key
+ )
+
+ msg.info(f"Span characteristics for spans_key '{spans_key}'")
+ msg.info("SD = Span Distinctiveness, BD = Boundary Distinctiveness")
+ _print_span_characteristics(span_characteristics)
+
+ _span_freqs = _get_spans_length_freq_dist(
+ gold_train_data["spans_length"][spans_key]
+ )
+ _filtered_span_freqs = _filter_spans_length_freq_dist(
+ _span_freqs, threshold=SPAN_LENGTH_THRESHOLD_PERCENTAGE
+ )
+
+ msg.info(
+ f"Over {SPAN_LENGTH_THRESHOLD_PERCENTAGE}% of spans have lengths of 1 -- "
+ f"{max(_filtered_span_freqs.keys())} "
+ f"(min={span_characteristics['min_length']}, max={span_characteristics['max_length']}). "
+ f"The most common span lengths are: {_format_freqs(_filtered_span_freqs)}. "
+ "If you are using the n-gram suggester, note that omitting "
+ "infrequent n-gram lengths can greatly improve speed and "
+ "memory usage."
+ )
+
+ msg.text(
+ f"Full distribution of span lengths: {_format_freqs(_span_freqs)}",
+ show=verbose,
+ )
+
+ # Add report regarding span characteristics
+ if span_characteristics["avg_sd"] < SPAN_DISTINCT_THRESHOLD:
+ msg.warn("Spans may not be distinct from the rest of the corpus")
+ else:
+ msg.good("Spans are distinct from the rest of the corpus")
+
+ p_spans = span_characteristics["p_spans"].values()
+ all_span_tokens: Counter = sum(p_spans, Counter())
+ most_common_spans = [w for w, _ in all_span_tokens.most_common(10)]
+ msg.text(
+ "10 most common span tokens: {}".format(
+ _format_labels(most_common_spans)
+ ),
+ show=verbose,
+ )
+
+ # Add report regarding span boundary characteristics
+ if span_characteristics["avg_bd"] < BOUNDARY_DISTINCT_THRESHOLD:
+ msg.warn("Boundary tokens are not distinct from the rest of the corpus")
+ else:
+ msg.good("Boundary tokens are distinct from the rest of the corpus")
+
+ p_bounds = span_characteristics["p_bounds"].values()
+ all_span_bound_tokens: Counter = sum(p_bounds, Counter())
+ most_common_bounds = [w for w, _ in all_span_bound_tokens.most_common(10)]
+ msg.text(
+ "10 most common span boundary tokens: {}".format(
+ _format_labels(most_common_bounds)
+ ),
+ show=verbose,
+ )
+
if has_low_data_warning:
msg.text(
f"To train a new span type, your data should include at "
@@ -282,7 +362,7 @@ def debug_data(
if label != "-"
]
labels_with_counts = _format_labels(labels_with_counts, counts=True)
- msg.text(f"Labels in train data: {_format_labels(labels)}", show=verbose)
+ msg.text(f"Labels in train data: {labels_with_counts}", show=verbose)
missing_labels = model_labels - labels
if missing_labels:
msg.warn(
@@ -638,6 +718,9 @@ def _compile_gold(
"words": Counter(),
"roots": Counter(),
"spancat": dict(),
+ "spans_length": dict(),
+ "spans_per_type": dict(),
+ "sb_per_type": dict(),
"ws_ents": 0,
"boundary_cross_ents": 0,
"n_words": 0,
@@ -676,21 +759,66 @@ def _compile_gold(
# "Illegal" whitespace entity
data["ws_ents"] += 1
if label.startswith(("B-", "U-")):
- combined_label = label.split("-")[1]
+ combined_label = remove_bilu_prefix(label)
data["ner"][combined_label] += 1
- if sent_starts[i] == True and label.startswith(("I-", "L-")):
+ if sent_starts[i] and label.startswith(("I-", "L-")):
data["boundary_cross_ents"] += 1
elif label == "-":
data["ner"]["-"] += 1
if "spancat" in factory_names:
- for span_key in list(eg.reference.spans.keys()):
- if span_key not in data["spancat"]:
- data["spancat"][span_key] = Counter()
- for i, span in enumerate(eg.reference.spans[span_key]):
+ for spans_key in list(eg.reference.spans.keys()):
+ # Obtain the span frequency
+ if spans_key not in data["spancat"]:
+ data["spancat"][spans_key] = Counter()
+ for i, span in enumerate(eg.reference.spans[spans_key]):
if span.label_ is None:
continue
else:
- data["spancat"][span_key][span.label_] += 1
+ data["spancat"][spans_key][span.label_] += 1
+
+ # Obtain the span length
+ if spans_key not in data["spans_length"]:
+ data["spans_length"][spans_key] = dict()
+ for span in gold.spans[spans_key]:
+ if span.label_ is None:
+ continue
+ if span.label_ not in data["spans_length"][spans_key]:
+ data["spans_length"][spans_key][span.label_] = []
+ data["spans_length"][spans_key][span.label_].append(len(span))
+
+ # Obtain spans per span type
+ if spans_key not in data["spans_per_type"]:
+ data["spans_per_type"][spans_key] = dict()
+ for span in gold.spans[spans_key]:
+ if span.label_ not in data["spans_per_type"][spans_key]:
+ data["spans_per_type"][spans_key][span.label_] = []
+ data["spans_per_type"][spans_key][span.label_].append(span)
+
+ # Obtain boundary tokens per span type
+ window_size = 1
+ if spans_key not in data["sb_per_type"]:
+ data["sb_per_type"][spans_key] = dict()
+ for span in gold.spans[spans_key]:
+ if span.label_ not in data["sb_per_type"][spans_key]:
+ # Creating a data structure that holds the start and
+ # end tokens for each span type
+ data["sb_per_type"][spans_key][span.label_] = {
+ "start": [],
+ "end": [],
+ }
+ for offset in range(window_size):
+ sb_start_idx = span.start - (offset + 1)
+ if sb_start_idx >= 0:
+ data["sb_per_type"][spans_key][span.label_]["start"].append(
+ gold[sb_start_idx : sb_start_idx + 1]
+ )
+
+ sb_end_idx = span.end + (offset + 1)
+ if sb_end_idx <= len(gold):
+ data["sb_per_type"][spans_key][span.label_]["end"].append(
+ gold[sb_end_idx - 1 : sb_end_idx]
+ )
+
if "textcat" in factory_names or "textcat_multilabel" in factory_names:
data["cats"].update(gold.cats)
if any(val not in (0, 1) for val in gold.cats.values()):
@@ -761,6 +889,16 @@ def _format_labels(
return ", ".join([f"'{l}'" for l in cast(Iterable[str], labels)])
+def _format_freqs(freqs: Dict[int, float], sort: bool = True) -> str:
+ if sort:
+ freqs = dict(sorted(freqs.items()))
+
+ _freqs = [(str(k), v) for k, v in freqs.items()]
+ return ", ".join(
+ [f"{l} ({c}%)" for l, c in cast(Iterable[Tuple[str, float]], _freqs)]
+ )
+
+
def _get_examples_without_label(
data: Sequence[Example],
label: str,
@@ -771,7 +909,7 @@ def _get_examples_without_label(
for eg in data:
if component == "ner":
labels = [
- label.split("-")[1]
+ remove_bilu_prefix(label)
for label in eg.get_aligned_ner()
if label not in ("O", "-", None)
]
@@ -797,6 +935,7 @@ def _get_labels_from_model(nlp: Language, factory_name: str) -> Set[str]:
labels: Set[str] = set()
for pipe_name in pipe_names:
pipe = nlp.get_pipe(pipe_name)
+ assert isinstance(pipe, TrainablePipe)
labels.update(pipe.labels)
return labels
@@ -815,3 +954,177 @@ def _get_labels_from_spancat(nlp: Language) -> Dict[str, Set[str]]:
labels[pipe.key] = set()
labels[pipe.key].update(pipe.labels)
return labels
+
+
+def _gmean(l: List) -> float:
+ """Compute geometric mean of a list"""
+ return math.exp(math.fsum(math.log(i) for i in l) / len(l))
+
+
+def _wgt_average(metric: Dict[str, float], frequencies: Counter) -> float:
+ total = sum(value * frequencies[span_type] for span_type, value in metric.items())
+ return total / sum(frequencies.values())
+
+
+def _get_distribution(docs, normalize: bool = True) -> Counter:
+ """Get the frequency distribution given a set of Docs"""
+ word_counts: Counter = Counter()
+ for doc in docs:
+ for token in doc:
+ # Normalize the text
+ t = token.text.lower().replace("``", '"').replace("''", '"')
+ word_counts[t] += 1
+ if normalize:
+ total = sum(word_counts.values(), 0.0)
+ word_counts = Counter({k: v / total for k, v in word_counts.items()})
+ return word_counts
+
+
+def _get_kl_divergence(p: Counter, q: Counter) -> float:
+ """Compute the Kullback-Leibler divergence from two frequency distributions"""
+ total = 0.0
+ for word, p_word in p.items():
+ total += p_word * math.log(p_word / q[word])
+ return total
+
+
+def _format_span_row(span_data: List[Dict], labels: List[str]) -> List[Any]:
+ """Compile into one list for easier reporting"""
+ d = {
+ label: [label] + list(_format_number(d[label]) for d in span_data)
+ for label in labels
+ }
+ return list(d.values())
+
+
+def _get_span_characteristics(
+ examples: List[Example], compiled_gold: Dict[str, Any], spans_key: str
+) -> Dict[str, Any]:
+ """Obtain all span characteristics"""
+ data_labels = compiled_gold["spancat"][spans_key]
+ # Get lengths
+ span_length = {
+ label: _gmean(l)
+ for label, l in compiled_gold["spans_length"][spans_key].items()
+ }
+ spans_per_type = {
+ label: len(spans)
+ for label, spans in compiled_gold["spans_per_type"][spans_key].items()
+ }
+ min_lengths = [min(l) for l in compiled_gold["spans_length"][spans_key].values()]
+ max_lengths = [max(l) for l in compiled_gold["spans_length"][spans_key].values()]
+
+ # Get relevant distributions: corpus, spans, span boundaries
+ p_corpus = _get_distribution([eg.reference for eg in examples], normalize=True)
+ p_spans = {
+ label: _get_distribution(spans, normalize=True)
+ for label, spans in compiled_gold["spans_per_type"][spans_key].items()
+ }
+ p_bounds = {
+ label: _get_distribution(sb["start"] + sb["end"], normalize=True)
+ for label, sb in compiled_gold["sb_per_type"][spans_key].items()
+ }
+
+ # Compute for actual span characteristics
+ span_distinctiveness = {
+ label: _get_kl_divergence(freq_dist, p_corpus)
+ for label, freq_dist in p_spans.items()
+ }
+ sb_distinctiveness = {
+ label: _get_kl_divergence(freq_dist, p_corpus)
+ for label, freq_dist in p_bounds.items()
+ }
+
+ return {
+ "sd": span_distinctiveness,
+ "bd": sb_distinctiveness,
+ "spans_per_type": spans_per_type,
+ "lengths": span_length,
+ "min_length": min(min_lengths),
+ "max_length": max(max_lengths),
+ "avg_sd": _wgt_average(span_distinctiveness, data_labels),
+ "avg_bd": _wgt_average(sb_distinctiveness, data_labels),
+ "avg_length": _wgt_average(span_length, data_labels),
+ "labels": list(data_labels.keys()),
+ "p_spans": p_spans,
+ "p_bounds": p_bounds,
+ }
+
+
+def _print_span_characteristics(span_characteristics: Dict[str, Any]):
+ """Print all span characteristics into a table"""
+ headers = ("Span Type", "Length", "SD", "BD", "N")
+ # Wasabi has this at 30 by default, but we might have some long labels
+ max_col = max(30, max(len(label) for label in span_characteristics["labels"]))
+ # Prepare table data with all span characteristics
+ table_data = [
+ span_characteristics["lengths"],
+ span_characteristics["sd"],
+ span_characteristics["bd"],
+ span_characteristics["spans_per_type"],
+ ]
+ table = _format_span_row(
+ span_data=table_data, labels=span_characteristics["labels"]
+ )
+ # Prepare table footer with weighted averages
+ footer_data = [
+ span_characteristics["avg_length"],
+ span_characteristics["avg_sd"],
+ span_characteristics["avg_bd"],
+ ]
+
+ footer = (
+ ["Wgt. Average"] + ["{:.2f}".format(round(f, 2)) for f in footer_data] + ["-"]
+ )
+ msg.table(
+ table,
+ footer=footer,
+ header=headers,
+ divider=True,
+ aligns=["l"] + ["r"] * (len(footer_data) + 1),
+ max_col=max_col,
+ )
+
+
+def _get_spans_length_freq_dist(
+ length_dict: Dict, threshold=SPAN_LENGTH_THRESHOLD_PERCENTAGE
+) -> Dict[int, float]:
+ """Get frequency distribution of spans length under a certain threshold"""
+ all_span_lengths = []
+ for _, lengths in length_dict.items():
+ all_span_lengths.extend(lengths)
+
+ freq_dist: Counter = Counter()
+ for i in all_span_lengths:
+ if freq_dist.get(i):
+ freq_dist[i] += 1
+ else:
+ freq_dist[i] = 1
+
+ # We will be working with percentages instead of raw counts
+ freq_dist_percentage = {}
+ for span_length, count in freq_dist.most_common():
+ percentage = (count / len(all_span_lengths)) * 100.0
+ percentage = round(percentage, 2)
+ freq_dist_percentage[span_length] = percentage
+
+ return freq_dist_percentage
+
+
+def _filter_spans_length_freq_dist(
+ freq_dist: Dict[int, float], threshold: int
+) -> Dict[int, float]:
+ """Filter frequency distribution with respect to a threshold
+
+ We're going to filter all the span lengths that fall
+ around a percentage threshold when summed.
+ """
+ total = 0.0
+ filtered_freq_dist = {}
+ for span_length, dist in freq_dist.items():
+ if total >= threshold:
+ break
+ else:
+ filtered_freq_dist[span_length] = dist
+ total += dist
+ return filtered_freq_dist
diff --git a/spacy/cli/debug_diff.py b/spacy/cli/debug_diff.py
new file mode 100644
index 000000000..6697c38ae
--- /dev/null
+++ b/spacy/cli/debug_diff.py
@@ -0,0 +1,89 @@
+from typing import Optional
+
+import typer
+from wasabi import Printer, diff_strings, MarkdownRenderer
+from pathlib import Path
+from thinc.api import Config
+
+from ._util import debug_cli, Arg, Opt, show_validation_error, parse_config_overrides
+from ..util import load_config
+from .init_config import init_config, Optimizations
+
+
+@debug_cli.command(
+ "diff-config",
+ context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+)
+def debug_diff_cli(
+ # fmt: off
+ ctx: typer.Context,
+ config_path: Path = Arg(..., help="Path to config file", exists=True, allow_dash=True),
+ compare_to: Optional[Path] = Opt(None, help="Path to a config file to diff against, or `None` to compare against default settings", exists=True, allow_dash=True),
+ optimize: Optimizations = Opt(Optimizations.efficiency.value, "--optimize", "-o", help="Whether the user config was optimized for efficiency or accuracy. Only relevant when comparing against the default config."),
+ gpu: bool = Opt(False, "--gpu", "-G", help="Whether the original config can run on a GPU. Only relevant when comparing against the default config."),
+ pretraining: bool = Opt(False, "--pretraining", "--pt", help="Whether to compare on a config with pretraining involved. Only relevant when comparing against the default config."),
+ markdown: bool = Opt(False, "--markdown", "-md", help="Generate Markdown for GitHub issues")
+ # fmt: on
+):
+ """Show a diff of a config file with respect to spaCy's defaults or another config file. If
+ additional settings were used in the creation of the config file, then you
+ must supply these as extra parameters to the command when comparing to the default settings. The generated diff
+ can also be used when posting to the discussion forum to provide more
+ information for the maintainers.
+
+ The `optimize`, `gpu`, and `pretraining` options are only relevant when
+ comparing against the default configuration (or specifically when `compare_to` is None).
+
+ DOCS: https://spacy.io/api/cli#debug-diff
+ """
+ debug_diff(
+ config_path=config_path,
+ compare_to=compare_to,
+ gpu=gpu,
+ optimize=optimize,
+ pretraining=pretraining,
+ markdown=markdown,
+ )
+
+
+def debug_diff(
+ config_path: Path,
+ compare_to: Optional[Path],
+ gpu: bool,
+ optimize: Optimizations,
+ pretraining: bool,
+ markdown: bool,
+):
+ msg = Printer()
+ with show_validation_error(hint_fill=False):
+ user_config = load_config(config_path)
+ if compare_to:
+ other_config = load_config(compare_to)
+ else:
+ # Recreate a default config based from user's config
+ lang = user_config["nlp"]["lang"]
+ pipeline = list(user_config["nlp"]["pipeline"])
+ msg.info(f"Found user-defined language: '{lang}'")
+ msg.info(f"Found user-defined pipelines: {pipeline}")
+ other_config = init_config(
+ lang=lang,
+ pipeline=pipeline,
+ optimize=optimize.value,
+ gpu=gpu,
+ pretraining=pretraining,
+ silent=True,
+ )
+
+ user = user_config.to_str()
+ other = other_config.to_str()
+
+ if user == other:
+ msg.warn("No diff to show: configs are identical")
+ else:
+ diff_text = diff_strings(other, user, add_symbols=markdown)
+ if markdown:
+ md = MarkdownRenderer()
+ md.add(md.code_block(diff_text, "diff"))
+ print(md.text)
+ else:
+ print(diff_text)
diff --git a/spacy/cli/download.py b/spacy/cli/download.py
index 4ea9a8f0e..0c9a32b93 100644
--- a/spacy/cli/download.py
+++ b/spacy/cli/download.py
@@ -7,6 +7,7 @@ import typer
from ._util import app, Arg, Opt, WHEEL_SUFFIX, SDIST_SUFFIX
from .. import about
from ..util import is_package, get_minor_version, run_command
+from ..util import is_prerelease_version
from ..errors import OLD_MODEL_SHORTCUTS
@@ -19,7 +20,7 @@ def download_cli(
ctx: typer.Context,
model: str = Arg(..., help="Name of pipeline package to download"),
direct: bool = Opt(False, "--direct", "-d", "-D", help="Force direct download of name + version"),
- sdist: bool = Opt(False, "--sdist", "-S", help="Download sdist (.tar.gz) archive instead of pre-built binary wheel")
+ sdist: bool = Opt(False, "--sdist", "-S", help="Download sdist (.tar.gz) archive instead of pre-built binary wheel"),
# fmt: on
):
"""
@@ -35,7 +36,12 @@ def download_cli(
download(model, direct, sdist, *ctx.args)
-def download(model: str, direct: bool = False, sdist: bool = False, *pip_args) -> None:
+def download(
+ model: str,
+ direct: bool = False,
+ sdist: bool = False,
+ *pip_args,
+) -> None:
if (
not (is_package("spacy") or is_package("spacy-nightly"))
and "--no-deps" not in pip_args
@@ -49,13 +55,10 @@ def download(model: str, direct: bool = False, sdist: bool = False, *pip_args) -
"dependencies, you'll have to install them manually."
)
pip_args = pip_args + ("--no-deps",)
- suffix = SDIST_SUFFIX if sdist else WHEEL_SUFFIX
- dl_tpl = "{m}-{v}/{m}-{v}{s}#egg={m}=={v}"
if direct:
components = model.split("-")
model_name = "".join(components[:-1])
version = components[-1]
- download_model(dl_tpl.format(m=model_name, v=version, s=suffix), pip_args)
else:
model_name = model
if model in OLD_MODEL_SHORTCUTS:
@@ -66,15 +69,31 @@ def download(model: str, direct: bool = False, sdist: bool = False, *pip_args) -
model_name = OLD_MODEL_SHORTCUTS[model]
compatibility = get_compatibility()
version = get_version(model_name, compatibility)
- download_model(dl_tpl.format(m=model_name, v=version, s=suffix), pip_args)
+
+ filename = get_model_filename(model_name, version, sdist)
+
+ download_model(filename, pip_args)
msg.good(
"Download and installation successful",
f"You can now load the package via spacy.load('{model_name}')",
)
+def get_model_filename(model_name: str, version: str, sdist: bool = False) -> str:
+ dl_tpl = "{m}-{v}/{m}-{v}{s}"
+ egg_tpl = "#egg={m}=={v}"
+ suffix = SDIST_SUFFIX if sdist else WHEEL_SUFFIX
+ filename = dl_tpl.format(m=model_name, v=version, s=suffix)
+ if sdist:
+ filename += egg_tpl.format(m=model_name, v=version)
+ return filename
+
+
def get_compatibility() -> dict:
- version = get_minor_version(about.__version__)
+ if is_prerelease_version(about.__version__):
+ version: Optional[str] = about.__version__
+ else:
+ version = get_minor_version(about.__version__)
r = requests.get(about.__compatibility__)
if r.status_code != 200:
msg.fail(
@@ -101,6 +120,11 @@ def get_version(model: str, comp: dict) -> str:
return comp[model][0]
+def get_latest_version(model: str) -> str:
+ comp = get_compatibility()
+ return get_version(model, comp)
+
+
def download_model(
filename: str, user_pip_args: Optional[Sequence[str]] = None
) -> None:
diff --git a/spacy/cli/evaluate.py b/spacy/cli/evaluate.py
index 0d08d2c5e..8f3d6b859 100644
--- a/spacy/cli/evaluate.py
+++ b/spacy/cli/evaluate.py
@@ -7,12 +7,15 @@ from thinc.api import fix_random_seed
from ..training import Corpus
from ..tokens import Doc
-from ._util import app, Arg, Opt, setup_gpu, import_code
+from ._util import app, Arg, Opt, setup_gpu, import_code, benchmark_cli
from ..scorer import Scorer
from .. import util
from .. import displacy
+@benchmark_cli.command(
+ "accuracy",
+)
@app.command("evaluate")
def evaluate_cli(
# fmt: off
@@ -36,7 +39,7 @@ def evaluate_cli(
dependency parses in a HTML file, set as output directory as the
displacy_path argument.
- DOCS: https://spacy.io/api/cli#evaluate
+ DOCS: https://spacy.io/api/cli#benchmark-accuracy
"""
import_code(code_path)
evaluate(
diff --git a/spacy/cli/find_threshold.py b/spacy/cli/find_threshold.py
new file mode 100644
index 000000000..efa664832
--- /dev/null
+++ b/spacy/cli/find_threshold.py
@@ -0,0 +1,233 @@
+import functools
+import operator
+from pathlib import Path
+import logging
+from typing import Optional, Tuple, Any, Dict, List
+
+import numpy
+import wasabi.tables
+
+from ..pipeline import TextCategorizer, MultiLabel_TextCategorizer
+from ..errors import Errors
+from ..training import Corpus
+from ._util import app, Arg, Opt, import_code, setup_gpu
+from .. import util
+
+_DEFAULTS = {
+ "n_trials": 11,
+ "use_gpu": -1,
+ "gold_preproc": False,
+}
+
+
+@app.command(
+ "find-threshold",
+ context_settings={"allow_extra_args": False, "ignore_unknown_options": True},
+)
+def find_threshold_cli(
+ # fmt: off
+ model: str = Arg(..., help="Model name or path"),
+ data_path: Path = Arg(..., help="Location of binary evaluation data in .spacy format", exists=True),
+ pipe_name: str = Arg(..., help="Name of pipe to examine thresholds for"),
+ threshold_key: str = Arg(..., help="Key of threshold attribute in component's configuration"),
+ scores_key: str = Arg(..., help="Metric to optimize"),
+ n_trials: int = Opt(_DEFAULTS["n_trials"], "--n_trials", "-n", help="Number of trials to determine optimal thresholds"),
+ code_path: Optional[Path] = Opt(None, "--code", "-c", help="Path to Python file with additional code (registered functions) to be imported"),
+ use_gpu: int = Opt(_DEFAULTS["use_gpu"], "--gpu-id", "-g", help="GPU ID or -1 for CPU"),
+ gold_preproc: bool = Opt(_DEFAULTS["gold_preproc"], "--gold-preproc", "-G", help="Use gold preprocessing"),
+ verbose: bool = Opt(False, "--silent", "-V", "-VV", help="Display more information for debugging purposes"),
+ # fmt: on
+):
+ """
+ Runs prediction trials for a trained model with varying tresholds to maximize
+ the specified metric. The search space for the threshold is traversed linearly
+ from 0 to 1 in `n_trials` steps. Results are displayed in a table on `stdout`
+ (the corresponding API call to `spacy.cli.find_threshold.find_threshold()`
+ returns all results).
+
+ This is applicable only for components whose predictions are influenced by
+ thresholds - e.g. `textcat_multilabel` and `spancat`, but not `textcat`. Note
+ that the full path to the corresponding threshold attribute in the config has to
+ be provided.
+
+ DOCS: https://spacy.io/api/cli#find-threshold
+ """
+
+ util.logger.setLevel(logging.DEBUG if verbose else logging.INFO)
+ import_code(code_path)
+ find_threshold(
+ model=model,
+ data_path=data_path,
+ pipe_name=pipe_name,
+ threshold_key=threshold_key,
+ scores_key=scores_key,
+ n_trials=n_trials,
+ use_gpu=use_gpu,
+ gold_preproc=gold_preproc,
+ silent=False,
+ )
+
+
+def find_threshold(
+ model: str,
+ data_path: Path,
+ pipe_name: str,
+ threshold_key: str,
+ scores_key: str,
+ *,
+ n_trials: int = _DEFAULTS["n_trials"], # type: ignore
+ use_gpu: int = _DEFAULTS["use_gpu"], # type: ignore
+ gold_preproc: bool = _DEFAULTS["gold_preproc"], # type: ignore
+ silent: bool = True,
+) -> Tuple[float, float, Dict[float, float]]:
+ """
+ Runs prediction trials for models with varying tresholds to maximize the specified metric.
+ model (Union[str, Path]): Pipeline to evaluate. Can be a package or a path to a data directory.
+ data_path (Path): Path to file with DocBin with docs to use for threshold search.
+ pipe_name (str): Name of pipe to examine thresholds for.
+ threshold_key (str): Key of threshold attribute in component's configuration.
+ scores_key (str): Name of score to metric to optimize.
+ n_trials (int): Number of trials to determine optimal thresholds.
+ use_gpu (int): GPU ID or -1 for CPU.
+ gold_preproc (bool): Whether to use gold preprocessing. Gold preprocessing helps the annotations align to the
+ tokenization, and may result in sequences of more consistent length. However, it may reduce runtime accuracy due
+ to train/test skew.
+ silent (bool): Whether to print non-error-related output to stdout.
+ RETURNS (Tuple[float, float, Dict[float, float]]): Best found threshold, the corresponding score, scores for all
+ evaluated thresholds.
+ """
+
+ setup_gpu(use_gpu, silent=silent)
+ data_path = util.ensure_path(data_path)
+ if not data_path.exists():
+ wasabi.msg.fail("Evaluation data not found", data_path, exits=1)
+ nlp = util.load_model(model)
+
+ if pipe_name not in nlp.component_names:
+ raise AttributeError(
+ Errors.E001.format(name=pipe_name, opts=nlp.component_names)
+ )
+ pipe = nlp.get_pipe(pipe_name)
+ if not hasattr(pipe, "scorer"):
+ raise AttributeError(Errors.E1045)
+
+ if type(pipe) == TextCategorizer:
+ wasabi.msg.warn(
+ "The `textcat` component doesn't use a threshold as it's not applicable to the concept of "
+ "exclusive classes. All thresholds will yield the same results."
+ )
+
+ if not silent:
+ wasabi.msg.info(
+ title=f"Optimizing for {scores_key} for component '{pipe_name}' with {n_trials} "
+ f"trials."
+ )
+
+ # Load evaluation corpus.
+ corpus = Corpus(data_path, gold_preproc=gold_preproc)
+ dev_dataset = list(corpus(nlp))
+ config_keys = threshold_key.split(".")
+
+ def set_nested_item(
+ config: Dict[str, Any], keys: List[str], value: float
+ ) -> Dict[str, Any]:
+ """Set item in nested dictionary. Adapted from https://stackoverflow.com/a/54138200.
+ config (Dict[str, Any]): Configuration dictionary.
+ keys (List[Any]): Path to value to set.
+ value (float): Value to set.
+ RETURNS (Dict[str, Any]): Updated dictionary.
+ """
+ functools.reduce(operator.getitem, keys[:-1], config)[keys[-1]] = value
+ return config
+
+ def filter_config(
+ config: Dict[str, Any], keys: List[str], full_key: str
+ ) -> Dict[str, Any]:
+ """Filters provided config dictionary so that only the specified keys path remains.
+ config (Dict[str, Any]): Configuration dictionary.
+ keys (List[Any]): Path to value to set.
+ full_key (str): Full user-specified key.
+ RETURNS (Dict[str, Any]): Filtered dictionary.
+ """
+ if keys[0] not in config:
+ wasabi.msg.fail(
+ title=f"Failed to look up `{full_key}` in config: sub-key {[keys[0]]} not found.",
+ text=f"Make sure you specified {[keys[0]]} correctly. The following sub-keys are available instead: "
+ f"{list(config.keys())}",
+ exits=1,
+ )
+ return {
+ keys[0]: filter_config(config[keys[0]], keys[1:], full_key)
+ if len(keys) > 1
+ else config[keys[0]]
+ }
+
+ # Evaluate with varying threshold values.
+ scores: Dict[float, float] = {}
+ config_keys_full = ["components", pipe_name, *config_keys]
+ table_col_widths = (10, 10)
+ thresholds = numpy.linspace(0, 1, n_trials)
+ print(wasabi.tables.row(["Threshold", f"{scores_key}"], widths=table_col_widths))
+ for threshold in thresholds:
+ # Reload pipeline with overrides specifying the new threshold.
+ nlp = util.load_model(
+ model,
+ config=set_nested_item(
+ filter_config(
+ nlp.config, config_keys_full, ".".join(config_keys_full)
+ ).copy(),
+ config_keys_full,
+ threshold,
+ ),
+ )
+ if hasattr(pipe, "cfg"):
+ setattr(
+ nlp.get_pipe(pipe_name),
+ "cfg",
+ set_nested_item(getattr(pipe, "cfg"), config_keys, threshold),
+ )
+
+ eval_scores = nlp.evaluate(dev_dataset)
+ if scores_key not in eval_scores:
+ wasabi.msg.fail(
+ title=f"Failed to look up score `{scores_key}` in evaluation results.",
+ text=f"Make sure you specified the correct value for `scores_key`. The following scores are "
+ f"available: {list(eval_scores.keys())}",
+ exits=1,
+ )
+ scores[threshold] = eval_scores[scores_key]
+
+ if not isinstance(scores[threshold], (float, int)):
+ wasabi.msg.fail(
+ f"Returned score for key '{scores_key}' is not numeric. Threshold optimization only works for numeric "
+ f"scores.",
+ exits=1,
+ )
+ print(
+ wasabi.row(
+ [round(threshold, 3), round(scores[threshold], 3)],
+ widths=table_col_widths,
+ )
+ )
+
+ best_threshold = max(scores.keys(), key=(lambda key: scores[key]))
+
+ # If all scores are identical, emit warning.
+ if len(set(scores.values())) == 1:
+ wasabi.msg.warn(
+ title="All scores are identical. Verify that all settings are correct.",
+ text=""
+ if (
+ not isinstance(pipe, MultiLabel_TextCategorizer)
+ or scores_key in ("cats_macro_f", "cats_micro_f")
+ )
+ else "Use `cats_macro_f` or `cats_micro_f` when optimizing the threshold for `textcat_multilabel`.",
+ )
+
+ else:
+ if not silent:
+ print(
+ f"\nBest threshold: {round(best_threshold, ndigits=4)} with {scores_key} value of {scores[best_threshold]}."
+ )
+
+ return best_threshold, scores[best_threshold], scores
diff --git a/spacy/cli/info.py b/spacy/cli/info.py
index e6a1cb616..974bc0f4e 100644
--- a/spacy/cli/info.py
+++ b/spacy/cli/info.py
@@ -1,10 +1,13 @@
from typing import Optional, Dict, Any, Union, List
import platform
+import pkg_resources
+import json
from pathlib import Path
from wasabi import Printer, MarkdownRenderer
import srsly
from ._util import app, Arg, Opt, string_to_list
+from .download import get_model_filename, get_latest_version
from .. import util
from .. import about
@@ -16,6 +19,7 @@ def info_cli(
markdown: bool = Opt(False, "--markdown", "-md", help="Generate Markdown for GitHub issues"),
silent: bool = Opt(False, "--silent", "-s", "-S", help="Don't print anything (just return)"),
exclude: str = Opt("labels", "--exclude", "-e", help="Comma-separated keys to exclude from the print-out"),
+ url: bool = Opt(False, "--url", "-u", help="Print the URL to download the most recent compatible version of the pipeline"),
# fmt: on
):
"""
@@ -23,10 +27,19 @@ def info_cli(
print its meta information. Flag --markdown prints details in Markdown for easy
copy-pasting to GitHub issues.
+ Flag --url prints only the download URL of the most recent compatible
+ version of the pipeline.
+
DOCS: https://spacy.io/api/cli#info
"""
exclude = string_to_list(exclude)
- info(model, markdown=markdown, silent=silent, exclude=exclude)
+ info(
+ model,
+ markdown=markdown,
+ silent=silent,
+ exclude=exclude,
+ url=url,
+ )
def info(
@@ -35,11 +48,20 @@ def info(
markdown: bool = False,
silent: bool = True,
exclude: Optional[List[str]] = None,
+ url: bool = False,
) -> Union[str, dict]:
msg = Printer(no_print=silent, pretty=not silent)
if not exclude:
exclude = []
- if model:
+ if url:
+ if model is not None:
+ title = f"Download info for pipeline '{model}'"
+ data = info_model_url(model)
+ print(data["download_url"])
+ return data
+ else:
+ msg.fail("--url option requires a pipeline name", exits=1)
+ elif model:
title = f"Info about pipeline '{model}'"
data = info_model(model, silent=silent)
else:
@@ -99,11 +121,44 @@ def info_model(model: str, *, silent: bool = True) -> Dict[str, Any]:
meta["source"] = str(model_path.resolve())
else:
meta["source"] = str(model_path)
+ download_url = info_installed_model_url(model)
+ if download_url:
+ meta["download_url"] = download_url
return {
k: v for k, v in meta.items() if k not in ("accuracy", "performance", "speed")
}
+def info_installed_model_url(model: str) -> Optional[str]:
+ """Given a pipeline name, get the download URL if available, otherwise
+ return None.
+
+ This is only available for pipelines installed as modules that have
+ dist-info available.
+ """
+ try:
+ dist = pkg_resources.get_distribution(model)
+ data = json.loads(dist.get_metadata("direct_url.json"))
+ return data["url"]
+ except pkg_resources.DistributionNotFound:
+ # no such package
+ return None
+ except Exception:
+ # something else, like no file or invalid JSON
+ return None
+
+
+def info_model_url(model: str) -> Dict[str, Any]:
+ """Return the download URL for the latest version of a pipeline."""
+ version = get_latest_version(model)
+
+ filename = get_model_filename(model, version)
+ download_url = about.__download_url__ + "/" + filename
+ release_tpl = "https://github.com/explosion/spacy-models/releases/tag/{m}-{v}"
+ release_url = release_tpl.format(m=model, v=version)
+ return {"download_url": download_url, "release_url": release_url}
+
+
def get_markdown(
data: Dict[str, Any],
title: Optional[str] = None,
diff --git a/spacy/cli/init_config.py b/spacy/cli/init_config.py
index d4cd939c2..b634caa4c 100644
--- a/spacy/cli/init_config.py
+++ b/spacy/cli/init_config.py
@@ -10,6 +10,7 @@ from jinja2 import Template
from .. import util
from ..language import DEFAULT_CONFIG_PRETRAIN_PATH
from ..schemas import RecommendationSchema
+from ..util import SimpleFrozenList
from ._util import init_cli, Arg, Opt, show_validation_error, COMMAND
from ._util import string_to_list, import_code
@@ -24,16 +25,30 @@ class Optimizations(str, Enum):
accuracy = "accuracy"
+class InitValues:
+ """
+ Default values for initialization. Dedicated class to allow synchronized default values for init_config_cli() and
+ init_config(), i.e. initialization calls via CLI respectively Python.
+ """
+
+ lang = "en"
+ pipeline = SimpleFrozenList(["tagger", "parser", "ner"])
+ optimize = Optimizations.efficiency
+ gpu = False
+ pretraining = False
+ force_overwrite = False
+
+
@init_cli.command("config")
def init_config_cli(
# fmt: off
output_file: Path = Arg(..., help="File to save the config to or - for stdout (will only output config and no additional logging info)", allow_dash=True),
- lang: str = Opt("en", "--lang", "-l", help="Two-letter code of the language to use"),
- pipeline: str = Opt("tagger,parser,ner", "--pipeline", "-p", help="Comma-separated names of trainable pipeline components to include (without 'tok2vec' or 'transformer')"),
- optimize: Optimizations = Opt(Optimizations.efficiency.value, "--optimize", "-o", help="Whether to optimize for efficiency (faster inference, smaller model, lower memory consumption) or higher accuracy (potentially larger and slower model). This will impact the choice of architecture, pretrained weights and related hyperparameters."),
- gpu: bool = Opt(False, "--gpu", "-G", help="Whether the model can run on GPU. This will impact the choice of architecture, pretrained weights and related hyperparameters."),
- pretraining: bool = Opt(False, "--pretraining", "-pt", help="Include config for pretraining (with 'spacy pretrain')"),
- force_overwrite: bool = Opt(False, "--force", "-F", help="Force overwriting the output file"),
+ lang: str = Opt(InitValues.lang, "--lang", "-l", help="Two-letter code of the language to use"),
+ pipeline: str = Opt(",".join(InitValues.pipeline), "--pipeline", "-p", help="Comma-separated names of trainable pipeline components to include (without 'tok2vec' or 'transformer')"),
+ optimize: Optimizations = Opt(InitValues.optimize, "--optimize", "-o", help="Whether to optimize for efficiency (faster inference, smaller model, lower memory consumption) or higher accuracy (potentially larger and slower model). This will impact the choice of architecture, pretrained weights and related hyperparameters."),
+ gpu: bool = Opt(InitValues.gpu, "--gpu", "-G", help="Whether the model can run on GPU. This will impact the choice of architecture, pretrained weights and related hyperparameters."),
+ pretraining: bool = Opt(InitValues.pretraining, "--pretraining", "-pt", help="Include config for pretraining (with 'spacy pretrain')"),
+ force_overwrite: bool = Opt(InitValues.force_overwrite, "--force", "-F", help="Force overwriting the output file"),
# fmt: on
):
"""
@@ -133,11 +148,11 @@ def fill_config(
def init_config(
*,
- lang: str,
- pipeline: List[str],
- optimize: str,
- gpu: bool,
- pretraining: bool = False,
+ lang: str = InitValues.lang,
+ pipeline: List[str] = InitValues.pipeline,
+ optimize: str = InitValues.optimize,
+ gpu: bool = InitValues.gpu,
+ pretraining: bool = InitValues.pretraining,
silent: bool = True,
) -> Config:
msg = Printer(no_print=silent)
diff --git a/spacy/cli/package.py b/spacy/cli/package.py
index b8c8397b6..324c5d1bb 100644
--- a/spacy/cli/package.py
+++ b/spacy/cli/package.py
@@ -299,8 +299,8 @@ def get_meta(
}
nlp = util.load_model_from_path(Path(model_path))
meta.update(nlp.meta)
- meta.update(existing_meta)
meta["spacy_version"] = util.get_minor_version_range(about.__version__)
+ meta.update(existing_meta)
meta["vectors"] = {
"width": nlp.vocab.vectors_length,
"vectors": len(nlp.vocab.vectors),
diff --git a/spacy/cli/pretrain.py b/spacy/cli/pretrain.py
index fe3ce0dad..381d589cf 100644
--- a/spacy/cli/pretrain.py
+++ b/spacy/cli/pretrain.py
@@ -61,7 +61,7 @@ def pretrain_cli(
# TODO: What's the solution here? How do we handle optional blocks?
msg.fail("The [pretraining] block in your config is empty", exits=1)
if not output_dir.exists():
- output_dir.mkdir()
+ output_dir.mkdir(parents=True)
msg.good(f"Created output directory: {output_dir}")
# Save non-interpolated config
raw_config.to_disk(output_dir / "config.cfg")
diff --git a/spacy/cli/project/assets.py b/spacy/cli/project/assets.py
index 5e0cdfdf2..8f35b2d23 100644
--- a/spacy/cli/project/assets.py
+++ b/spacy/cli/project/assets.py
@@ -12,6 +12,9 @@ from .._util import project_cli, Arg, Opt, PROJECT_FILE, load_project_config
from .._util import get_checksum, download_file, git_checkout, get_git_version
from .._util import SimpleFrozenDict, parse_config_overrides
+# Whether assets are extra if `extra` is not set.
+EXTRA_DEFAULT = False
+
@project_cli.command(
"assets",
@@ -21,7 +24,8 @@ def project_assets_cli(
# fmt: off
ctx: typer.Context, # This is only used to read additional arguments
project_dir: Path = Arg(Path.cwd(), help="Path to cloned project. Defaults to current working directory.", exists=True, file_okay=False),
- sparse_checkout: bool = Opt(False, "--sparse", "-S", help="Use sparse checkout for assets provided via Git, to only check out and clone the files needed. Requires Git v22.2+.")
+ sparse_checkout: bool = Opt(False, "--sparse", "-S", help="Use sparse checkout for assets provided via Git, to only check out and clone the files needed. Requires Git v22.2+."),
+ extra: bool = Opt(False, "--extra", "-e", help="Download all assets, including those marked as 'extra'.")
# fmt: on
):
"""Fetch project assets like datasets and pretrained weights. Assets are
@@ -32,7 +36,12 @@ def project_assets_cli(
DOCS: https://spacy.io/api/cli#project-assets
"""
overrides = parse_config_overrides(ctx.args)
- project_assets(project_dir, overrides=overrides, sparse_checkout=sparse_checkout)
+ project_assets(
+ project_dir,
+ overrides=overrides,
+ sparse_checkout=sparse_checkout,
+ extra=extra,
+ )
def project_assets(
@@ -40,17 +49,29 @@ def project_assets(
*,
overrides: Dict[str, Any] = SimpleFrozenDict(),
sparse_checkout: bool = False,
+ extra: bool = False,
) -> None:
"""Fetch assets for a project using DVC if possible.
project_dir (Path): Path to project directory.
+ sparse_checkout (bool): Use sparse checkout for assets provided via Git, to only check out and clone the files
+ needed.
+ extra (bool): Whether to download all assets, including those marked as 'extra'.
"""
project_path = ensure_path(project_dir)
config = load_project_config(project_path, overrides=overrides)
- assets = config.get("assets", {})
+ assets = [
+ asset
+ for asset in config.get("assets", [])
+ if extra or not asset.get("extra", EXTRA_DEFAULT)
+ ]
if not assets:
- msg.warn(f"No assets specified in {PROJECT_FILE}", exits=0)
+ msg.warn(
+ f"No assets specified in {PROJECT_FILE} (if assets are marked as extra, download them with --extra)",
+ exits=0,
+ )
msg.info(f"Fetching {len(assets)} asset(s)")
+
for asset in assets:
dest = (project_dir / asset["dest"]).resolve()
checksum = asset.get("checksum")
@@ -168,7 +189,11 @@ def convert_asset_url(url: str) -> str:
RETURNS (str): The converted URL.
"""
# If the asset URL is a regular GitHub URL it's likely a mistake
- if re.match(r"(http(s?)):\/\/github.com", url) and "releases/download" not in url:
+ if (
+ re.match(r"(http(s?)):\/\/github.com", url)
+ and "releases/download" not in url
+ and "/raw/" not in url
+ ):
converted = url.replace("github.com", "raw.githubusercontent.com")
converted = re.sub(r"/(tree|blob)/", "/", converted)
msg.warn(
diff --git a/spacy/cli/project/clone.py b/spacy/cli/project/clone.py
index 360ee3428..14b4ed9b5 100644
--- a/spacy/cli/project/clone.py
+++ b/spacy/cli/project/clone.py
@@ -7,11 +7,11 @@ import re
from ... import about
from ...util import ensure_path
from .._util import project_cli, Arg, Opt, COMMAND, PROJECT_FILE
-from .._util import git_checkout, get_git_version
+from .._util import git_checkout, get_git_version, git_repo_branch_exists
DEFAULT_REPO = about.__projects__
DEFAULT_PROJECTS_BRANCH = about.__projects_branch__
-DEFAULT_BRANCH = "master"
+DEFAULT_BRANCHES = ["main", "master"]
@project_cli.command("clone")
@@ -20,7 +20,7 @@ def project_clone_cli(
name: str = Arg(..., help="The name of the template to clone"),
dest: Optional[Path] = Arg(None, help="Where to clone the project. Defaults to current working directory", exists=False),
repo: str = Opt(DEFAULT_REPO, "--repo", "-r", help="The repository to clone from"),
- branch: Optional[str] = Opt(None, "--branch", "-b", help="The branch to clone from"),
+ branch: Optional[str] = Opt(None, "--branch", "-b", help=f"The branch to clone from. If not provided, will attempt {', '.join(DEFAULT_BRANCHES)}"),
sparse_checkout: bool = Opt(False, "--sparse", "-S", help="Use sparse Git checkout to only check out and clone the files needed. Requires Git v22.2+.")
# fmt: on
):
@@ -33,9 +33,25 @@ def project_clone_cli(
"""
if dest is None:
dest = Path.cwd() / Path(name).parts[-1]
+ if repo == DEFAULT_REPO and branch is None:
+ branch = DEFAULT_PROJECTS_BRANCH
+
if branch is None:
- # If it's a user repo, we want to default to other branch
- branch = DEFAULT_PROJECTS_BRANCH if repo == DEFAULT_REPO else DEFAULT_BRANCH
+ for default_branch in DEFAULT_BRANCHES:
+ if git_repo_branch_exists(repo, default_branch):
+ branch = default_branch
+ break
+ if branch is None:
+ default_branches_msg = ", ".join(f"'{b}'" for b in DEFAULT_BRANCHES)
+ msg.fail(
+ "No branch provided and attempted default "
+ f"branches {default_branches_msg} do not exist.",
+ exits=1,
+ )
+ else:
+ if not git_repo_branch_exists(repo, branch):
+ msg.fail(f"repo: {repo} (branch: {branch}) does not exist.", exits=1)
+ assert isinstance(branch, str)
project_clone(name, dest, repo=repo, branch=branch, sparse_checkout=sparse_checkout)
@@ -61,9 +77,9 @@ def project_clone(
try:
git_checkout(repo, name, dest, branch=branch, sparse=sparse_checkout)
except subprocess.CalledProcessError:
- err = f"Could not clone '{name}' from repo '{repo_name}'"
+ err = f"Could not clone '{name}' from repo '{repo_name}' (branch '{branch}')"
msg.fail(err, exits=1)
- msg.good(f"Cloned '{name}' from {repo_name}", project_dir)
+ msg.good(f"Cloned '{name}' from '{repo_name}' (branch '{branch}')", project_dir)
if not (project_dir / PROJECT_FILE).exists():
msg.warn(f"No {PROJECT_FILE} found in directory")
else:
diff --git a/spacy/cli/project/dvc.py b/spacy/cli/project/dvc.py
index 83dc5efbf..a15353855 100644
--- a/spacy/cli/project/dvc.py
+++ b/spacy/cli/project/dvc.py
@@ -25,6 +25,7 @@ def project_update_dvc_cli(
project_dir: Path = Arg(Path.cwd(), help="Location of project directory. Defaults to current working directory.", exists=True, file_okay=False),
workflow: Optional[str] = Arg(None, help=f"Name of workflow defined in {PROJECT_FILE}. Defaults to first workflow if not set."),
verbose: bool = Opt(False, "--verbose", "-V", help="Print more info"),
+ quiet: bool = Opt(False, "--quiet", "-q", help="Print less info"),
force: bool = Opt(False, "--force", "-F", help="Force update DVC config"),
# fmt: on
):
@@ -36,7 +37,7 @@ def project_update_dvc_cli(
DOCS: https://spacy.io/api/cli#project-dvc
"""
- project_update_dvc(project_dir, workflow, verbose=verbose, force=force)
+ project_update_dvc(project_dir, workflow, verbose=verbose, quiet=quiet, force=force)
def project_update_dvc(
@@ -44,6 +45,7 @@ def project_update_dvc(
workflow: Optional[str] = None,
*,
verbose: bool = False,
+ quiet: bool = False,
force: bool = False,
) -> None:
"""Update the auto-generated Data Version Control (DVC) config file. A DVC
@@ -54,11 +56,12 @@ def project_update_dvc(
workflow (Optional[str]): Optional name of workflow defined in project.yml.
If not set, the first workflow will be used.
verbose (bool): Print more info.
+ quiet (bool): Print less info.
force (bool): Force update DVC config.
"""
config = load_project_config(project_dir)
updated = update_dvc_config(
- project_dir, config, workflow, verbose=verbose, force=force
+ project_dir, config, workflow, verbose=verbose, quiet=quiet, force=force
)
help_msg = "To execute the workflow with DVC, run: dvc repro"
if updated:
@@ -72,7 +75,7 @@ def update_dvc_config(
config: Dict[str, Any],
workflow: Optional[str] = None,
verbose: bool = False,
- silent: bool = False,
+ quiet: bool = False,
force: bool = False,
) -> bool:
"""Re-run the DVC commands in dry mode and update dvc.yaml file in the
@@ -83,7 +86,7 @@ def update_dvc_config(
path (Path): The path to the project directory.
config (Dict[str, Any]): The loaded project.yml.
verbose (bool): Whether to print additional info (via DVC).
- silent (bool): Don't output anything (via DVC).
+ quiet (bool): Don't output anything (via DVC).
force (bool): Force update, even if hashes match.
RETURNS (bool): Whether the DVC config file was updated.
"""
@@ -105,6 +108,14 @@ def update_dvc_config(
dvc_config_path.unlink()
dvc_commands = []
config_commands = {cmd["name"]: cmd for cmd in config.get("commands", [])}
+
+ # some flags that apply to every command
+ flags = []
+ if verbose:
+ flags.append("--verbose")
+ if quiet:
+ flags.append("--quiet")
+
for name in workflows[workflow]:
command = config_commands[name]
deps = command.get("deps", [])
@@ -118,14 +129,26 @@ def update_dvc_config(
deps_cmd = [c for cl in [["-d", p] for p in deps] for c in cl]
outputs_cmd = [c for cl in [["-o", p] for p in outputs] for c in cl]
outputs_nc_cmd = [c for cl in [["-O", p] for p in outputs_no_cache] for c in cl]
- dvc_cmd = ["run", "-n", name, "-w", str(path), "--no-exec"]
+
+ dvc_cmd = ["run", *flags, "-n", name, "-w", str(path), "--no-exec"]
if command.get("no_skip"):
dvc_cmd.append("--always-changed")
full_cmd = [*dvc_cmd, *deps_cmd, *outputs_cmd, *outputs_nc_cmd, *project_cmd]
dvc_commands.append(join_command(full_cmd))
+
+ if not dvc_commands:
+ # If we don't check for this, then there will be an error when reading the
+ # config, since DVC wouldn't create it.
+ msg.fail(
+ "No usable commands for DVC found. This can happen if none of your "
+ "commands have dependencies or outputs.",
+ exits=1,
+ )
+
with working_dir(path):
- dvc_flags = {"--verbose": verbose, "--quiet": silent}
- run_dvc_commands(dvc_commands, flags=dvc_flags)
+ for c in dvc_commands:
+ dvc_command = "dvc " + c
+ run_command(dvc_command)
with dvc_config_path.open("r+", encoding="utf8") as f:
content = f.read()
f.seek(0, 0)
@@ -133,26 +156,6 @@ def update_dvc_config(
return True
-def run_dvc_commands(
- commands: Iterable[str] = SimpleFrozenList(), flags: Dict[str, bool] = {}
-) -> None:
- """Run a sequence of DVC commands in a subprocess, in order.
-
- commands (List[str]): The string commands without the leading "dvc".
- flags (Dict[str, bool]): Conditional flags to be added to command. Makes it
- easier to pass flags like --quiet that depend on a variable or
- command-line setting while avoiding lots of nested conditionals.
- """
- for c in commands:
- command = split_command(c)
- dvc_command = ["dvc", *command]
- # Add the flags if they are set to True
- for flag, is_active in flags.items():
- if is_active:
- dvc_command.append(flag)
- run_command(dvc_command)
-
-
def check_workflows(workflows: List[str], workflow: Optional[str] = None) -> None:
"""Validate workflows provided in project.yml and check that a given
workflow can be used to generate a DVC config.
diff --git a/spacy/cli/project/remote_storage.py b/spacy/cli/project/remote_storage.py
index 336a4bcb3..076541580 100644
--- a/spacy/cli/project/remote_storage.py
+++ b/spacy/cli/project/remote_storage.py
@@ -5,14 +5,17 @@ import hashlib
import urllib.parse
import tarfile
from pathlib import Path
+from wasabi import msg
-from .._util import get_hash, get_checksum, download_file, ensure_pathy
-from ...util import make_tempdir, get_minor_version, ENV_VARS, check_bool_env_var
+from .._util import get_hash, get_checksum, upload_file, download_file
+from .._util import ensure_pathy, make_tempdir
+from ...util import get_minor_version, ENV_VARS, check_bool_env_var
from ...git_info import GIT_VERSION
from ... import about
+from ...errors import Errors
if TYPE_CHECKING:
- from pathy import Pathy # noqa: F401
+ from pathy import FluidPath # noqa: F401
class RemoteStorage:
@@ -27,7 +30,7 @@ class RemoteStorage:
self.url = ensure_pathy(url)
self.compression = compression
- def push(self, path: Path, command_hash: str, content_hash: str) -> "Pathy":
+ def push(self, path: Path, command_hash: str, content_hash: str) -> "FluidPath":
"""Compress a file or directory within a project and upload it to a remote
storage. If an object exists at the full URL, nothing is done.
@@ -48,9 +51,7 @@ class RemoteStorage:
mode_string = f"w:{self.compression}" if self.compression else "w"
with tarfile.open(tar_loc, mode=mode_string) as tar_file:
tar_file.add(str(loc), arcname=str(path))
- with tar_loc.open(mode="rb") as input_file:
- with url.open(mode="wb") as output_file:
- output_file.write(input_file.read())
+ upload_file(tar_loc, url)
return url
def pull(
@@ -59,7 +60,7 @@ class RemoteStorage:
*,
command_hash: Optional[str] = None,
content_hash: Optional[str] = None,
- ) -> Optional["Pathy"]:
+ ) -> Optional["FluidPath"]:
"""Retrieve a file from the remote cache. If the file already exists,
nothing is done.
@@ -84,7 +85,23 @@ class RemoteStorage:
with tarfile.open(tar_loc, mode=mode_string) as tar_file:
# This requires that the path is added correctly, relative
# to root. This is how we set things up in push()
- tar_file.extractall(self.root)
+
+ # Disallow paths outside the current directory for the tar
+ # file (CVE-2007-4559, directory traversal vulnerability)
+ def is_within_directory(directory, target):
+ abs_directory = os.path.abspath(directory)
+ abs_target = os.path.abspath(target)
+ prefix = os.path.commonprefix([abs_directory, abs_target])
+ return prefix == abs_directory
+
+ def safe_extract(tar, path):
+ for member in tar.getmembers():
+ member_path = os.path.join(path, member.name)
+ if not is_within_directory(path, member_path):
+ raise ValueError(Errors.E852)
+ tar.extractall(path)
+
+ safe_extract(tar_file, self.root)
return url
def find(
@@ -93,25 +110,37 @@ class RemoteStorage:
*,
command_hash: Optional[str] = None,
content_hash: Optional[str] = None,
- ) -> Optional["Pathy"]:
+ ) -> Optional["FluidPath"]:
"""Find the best matching version of a file within the storage,
or `None` if no match can be found. If both the creation and content hash
are specified, only exact matches will be returned. Otherwise, the most
recent matching file is preferred.
"""
name = self.encode_name(str(path))
+ urls = []
if command_hash is not None and content_hash is not None:
- url = self.make_url(path, command_hash, content_hash)
+ url = self.url / name / command_hash / content_hash
urls = [url] if url.exists() else []
elif command_hash is not None:
- urls = list((self.url / name / command_hash).iterdir())
+ if (self.url / name / command_hash).exists():
+ urls = list((self.url / name / command_hash).iterdir())
else:
- urls = list((self.url / name).iterdir())
- if content_hash is not None:
- urls = [url for url in urls if url.parts[-1] == content_hash]
+ if (self.url / name).exists():
+ for sub_dir in (self.url / name).iterdir():
+ urls.extend(sub_dir.iterdir())
+ if content_hash is not None:
+ urls = [url for url in urls if url.parts[-1] == content_hash]
+ if len(urls) >= 2:
+ try:
+ urls.sort(key=lambda x: x.stat().last_modified) # type: ignore
+ except Exception:
+ msg.warn(
+ "Unable to sort remote files by last modified. The file(s) "
+ "pulled from the cache may not be the most recent."
+ )
return urls[-1] if urls else None
- def make_url(self, path: Path, command_hash: str, content_hash: str) -> "Pathy":
+ def make_url(self, path: Path, command_hash: str, content_hash: str) -> "FluidPath":
"""Construct a URL from a subpath, a creation hash and a content hash."""
return self.url / self.encode_name(str(path)) / command_hash / content_hash
diff --git a/spacy/cli/project/run.py b/spacy/cli/project/run.py
index 734803bc4..6dd174902 100644
--- a/spacy/cli/project/run.py
+++ b/spacy/cli/project/run.py
@@ -1,5 +1,8 @@
-from typing import Optional, List, Dict, Sequence, Any, Iterable
+from typing import Optional, List, Dict, Sequence, Any, Iterable, Tuple
+import os.path
from pathlib import Path
+
+import pkg_resources
from wasabi import msg
from wasabi.util import locale_escape
import sys
@@ -50,6 +53,7 @@ def project_run(
force: bool = False,
dry: bool = False,
capture: bool = False,
+ skip_requirements_check: bool = False,
) -> None:
"""Run a named script defined in the project.yml. If the script is part
of the default pipeline (defined in the "run" section), DVC is used to
@@ -66,11 +70,19 @@ def project_run(
sys.exit will be called with the return code. You should use capture=False
when you want to turn over execution to the command, and capture=True
when you want to run the command more like a function.
+ skip_requirements_check (bool): Whether to skip the requirements check.
"""
config = load_project_config(project_dir, overrides=overrides)
commands = {cmd["name"]: cmd for cmd in config.get("commands", [])}
workflows = config.get("workflows", {})
validate_subcommand(list(commands.keys()), list(workflows.keys()), subcommand)
+
+ req_path = project_dir / "requirements.txt"
+ if not skip_requirements_check:
+ if config.get("check_requirements", True) and os.path.exists(req_path):
+ with req_path.open() as requirements_file:
+ _check_requirements([req.strip() for req in requirements_file])
+
if subcommand in workflows:
msg.info(f"Running workflow '{subcommand}'")
for cmd in workflows[subcommand]:
@@ -81,6 +93,7 @@ def project_run(
force=force,
dry=dry,
capture=capture,
+ skip_requirements_check=True,
)
else:
cmd = commands[subcommand]
@@ -88,8 +101,8 @@ def project_run(
if not (project_dir / dep).exists():
err = f"Missing dependency specified by command '{subcommand}': {dep}"
err_help = "Maybe you forgot to run the 'project assets' command or a previous step?"
- err_kwargs = {"exits": 1} if not dry else {}
- msg.fail(err, err_help, **err_kwargs)
+ err_exits = 1 if not dry else None
+ msg.fail(err, err_help, exits=err_exits)
check_spacy_commit = check_bool_env_var(ENV_VARS.PROJECT_USE_GIT_VERSION)
with working_dir(project_dir) as current_dir:
msg.divider(subcommand)
@@ -195,6 +208,8 @@ def validate_subcommand(
msg.fail(f"No commands or workflows defined in {PROJECT_FILE}", exits=1)
if subcommand not in commands and subcommand not in workflows:
help_msg = []
+ if subcommand in ["assets", "asset"]:
+ help_msg.append("Did you mean to run: python -m spacy project assets?")
if commands:
help_msg.append(f"Available commands: {', '.join(commands)}")
if workflows:
@@ -308,3 +323,38 @@ def get_fileinfo(project_dir: Path, paths: List[str]) -> List[Dict[str, Optional
md5 = get_checksum(file_path) if file_path.exists() else None
data.append({"path": path, "md5": md5})
return data
+
+
+def _check_requirements(requirements: List[str]) -> Tuple[bool, bool]:
+ """Checks whether requirements are installed and free of version conflicts.
+ requirements (List[str]): List of requirements.
+ RETURNS (Tuple[bool, bool]): Whether (1) any packages couldn't be imported, (2) any packages with version conflicts
+ exist.
+ """
+
+ failed_pkgs_msgs: List[str] = []
+ conflicting_pkgs_msgs: List[str] = []
+
+ for req in requirements:
+ try:
+ pkg_resources.require(req)
+ except pkg_resources.DistributionNotFound as dnf:
+ failed_pkgs_msgs.append(dnf.report())
+ except pkg_resources.VersionConflict as vc:
+ conflicting_pkgs_msgs.append(vc.report())
+ except Exception:
+ msg.warn(
+ f"Unable to check requirement: {req} "
+ "Checks are currently limited to requirement specifiers "
+ "(PEP 508)"
+ )
+
+ if len(failed_pkgs_msgs) or len(conflicting_pkgs_msgs):
+ msg.warn(
+ title="Missing requirements or requirement conflicts detected. Make sure your Python environment is set up "
+ "correctly and you installed all requirements specified in your project's requirements.txt: "
+ )
+ for pgk_msg in failed_pkgs_msgs + conflicting_pkgs_msgs:
+ msg.text(pgk_msg)
+
+ return len(failed_pkgs_msgs) > 0, len(conflicting_pkgs_msgs) > 0
diff --git a/spacy/cli/templates/quickstart_training.jinja b/spacy/cli/templates/quickstart_training.jinja
index fb79a4f60..b961ac892 100644
--- a/spacy/cli/templates/quickstart_training.jinja
+++ b/spacy/cli/templates/quickstart_training.jinja
@@ -1,8 +1,9 @@
{# This is a template for training configs used for the quickstart widget in
the docs and the init config command. It encodes various best practices and
can help generate the best possible configuration, given a user's requirements. #}
-{%- set use_transformer = hardware != "cpu" -%}
+{%- set use_transformer = hardware != "cpu" and transformer_data -%}
{%- set transformer = transformer_data[optimize] if use_transformer else {} -%}
+{%- set listener_components = ["tagger", "morphologizer", "parser", "ner", "textcat", "textcat_multilabel", "entity_linker", "spancat", "trainable_lemmatizer"] -%}
[paths]
train = null
dev = null
@@ -24,10 +25,10 @@ lang = "{{ lang }}"
{%- set has_textcat = ("textcat" in components or "textcat_multilabel" in components) -%}
{%- set with_accuracy = optimize == "accuracy" -%}
{%- set has_accurate_textcat = has_textcat and with_accuracy -%}
-{%- if ("tagger" in components or "morphologizer" in components or "parser" in components or "ner" in components or "entity_linker" in components or has_accurate_textcat) -%}
-{%- set full_pipeline = ["transformer" if use_transformer else "tok2vec"] + components %}
+{%- if ("tagger" in components or "morphologizer" in components or "parser" in components or "ner" in components or "spancat" in components or "trainable_lemmatizer" in components or "entity_linker" in components or has_accurate_textcat) -%}
+{%- set full_pipeline = ["transformer" if use_transformer else "tok2vec"] + components -%}
{%- else -%}
-{%- set full_pipeline = components %}
+{%- set full_pipeline = components -%}
{%- endif %}
pipeline = {{ full_pipeline|pprint()|replace("'", '"')|safe }}
batch_size = {{ 128 if hardware == "gpu" else 1000 }}
@@ -54,7 +55,7 @@ stride = 96
factory = "morphologizer"
[components.morphologizer.model]
-@architectures = "spacy.Tagger.v1"
+@architectures = "spacy.Tagger.v2"
nO = null
[components.morphologizer.model.tok2vec]
@@ -70,7 +71,7 @@ grad_factor = 1.0
factory = "tagger"
[components.tagger.model]
-@architectures = "spacy.Tagger.v1"
+@architectures = "spacy.Tagger.v2"
nO = null
[components.tagger.model.tok2vec]
@@ -123,6 +124,60 @@ grad_factor = 1.0
@layers = "reduce_mean.v1"
{% endif -%}
+{% if "spancat" in components -%}
+[components.spancat]
+factory = "spancat"
+max_positive = null
+scorer = {"@scorers":"spacy.spancat_scorer.v1"}
+spans_key = "sc"
+threshold = 0.5
+
+[components.spancat.model]
+@architectures = "spacy.SpanCategorizer.v1"
+
+[components.spancat.model.reducer]
+@layers = "spacy.mean_max_reducer.v1"
+hidden_size = 128
+
+[components.spancat.model.scorer]
+@layers = "spacy.LinearLogistic.v1"
+nO = null
+nI = null
+
+[components.spancat.model.tok2vec]
+@architectures = "spacy-transformers.TransformerListener.v1"
+grad_factor = 1.0
+
+[components.spancat.model.tok2vec.pooling]
+@layers = "reduce_mean.v1"
+
+[components.spancat.suggester]
+@misc = "spacy.ngram_suggester.v1"
+sizes = [1,2,3]
+{% endif -%}
+
+{% if "trainable_lemmatizer" in components -%}
+[components.trainable_lemmatizer]
+factory = "trainable_lemmatizer"
+backoff = "orth"
+min_tree_freq = 3
+overwrite = false
+scorer = {"@scorers":"spacy.lemmatizer_scorer.v1"}
+top_k = 1
+
+[components.trainable_lemmatizer.model]
+@architectures = "spacy.Tagger.v2"
+nO = null
+normalize = false
+
+[components.trainable_lemmatizer.model.tok2vec]
+@architectures = "spacy-transformers.TransformerListener.v1"
+grad_factor = 1.0
+
+[components.trainable_lemmatizer.model.tok2vec.pooling]
+@layers = "reduce_mean.v1"
+{% endif -%}
+
{% if "entity_linker" in components -%}
[components.entity_linker]
factory = "entity_linker"
@@ -131,7 +186,7 @@ incl_context = true
incl_prior = true
[components.entity_linker.model]
-@architectures = "spacy.EntityLinker.v1"
+@architectures = "spacy.EntityLinker.v2"
nO = null
[components.entity_linker.model.tok2vec]
@@ -216,13 +271,8 @@ factory = "tok2vec"
[components.tok2vec.model.embed]
@architectures = "spacy.MultiHashEmbed.v2"
width = ${components.tok2vec.model.encode.width}
-{% if has_letters -%}
attrs = ["NORM", "PREFIX", "SUFFIX", "SHAPE"]
-rows = [5000, 2500, 2500, 2500]
-{% else -%}
-attrs = ["ORTH", "SHAPE"]
-rows = [5000, 2500]
-{% endif -%}
+rows = [5000, 1000, 2500, 2500]
include_static_vectors = {{ "true" if optimize == "accuracy" else "false" }}
[components.tok2vec.model.encode]
@@ -238,7 +288,7 @@ maxout_pieces = 3
factory = "morphologizer"
[components.morphologizer.model]
-@architectures = "spacy.Tagger.v1"
+@architectures = "spacy.Tagger.v2"
nO = null
[components.morphologizer.model.tok2vec]
@@ -251,7 +301,7 @@ width = ${components.tok2vec.model.encode.width}
factory = "tagger"
[components.tagger.model]
-@architectures = "spacy.Tagger.v1"
+@architectures = "spacy.Tagger.v2"
nO = null
[components.tagger.model.tok2vec]
@@ -295,6 +345,54 @@ nO = null
width = ${components.tok2vec.model.encode.width}
{% endif %}
+{% if "spancat" in components %}
+[components.spancat]
+factory = "spancat"
+max_positive = null
+scorer = {"@scorers":"spacy.spancat_scorer.v1"}
+spans_key = "sc"
+threshold = 0.5
+
+[components.spancat.model]
+@architectures = "spacy.SpanCategorizer.v1"
+
+[components.spancat.model.reducer]
+@layers = "spacy.mean_max_reducer.v1"
+hidden_size = 128
+
+[components.spancat.model.scorer]
+@layers = "spacy.LinearLogistic.v1"
+nO = null
+nI = null
+
+[components.spancat.model.tok2vec]
+@architectures = "spacy.Tok2VecListener.v1"
+width = ${components.tok2vec.model.encode.width}
+
+[components.spancat.suggester]
+@misc = "spacy.ngram_suggester.v1"
+sizes = [1,2,3]
+{% endif %}
+
+{% if "trainable_lemmatizer" in components -%}
+[components.trainable_lemmatizer]
+factory = "trainable_lemmatizer"
+backoff = "orth"
+min_tree_freq = 3
+overwrite = false
+scorer = {"@scorers":"spacy.lemmatizer_scorer.v1"}
+top_k = 1
+
+[components.trainable_lemmatizer.model]
+@architectures = "spacy.Tagger.v2"
+nO = null
+normalize = false
+
+[components.trainable_lemmatizer.model.tok2vec]
+@architectures = "spacy.Tok2VecListener.v1"
+width = ${components.tok2vec.model.encode.width}
+{% endif -%}
+
{% if "entity_linker" in components -%}
[components.entity_linker]
factory = "entity_linker"
@@ -303,7 +401,7 @@ incl_context = true
incl_prior = true
[components.entity_linker.model]
-@architectures = "spacy.EntityLinker.v1"
+@architectures = "spacy.EntityLinker.v2"
nO = null
[components.entity_linker.model.tok2vec]
@@ -369,7 +467,7 @@ no_output_layer = false
{% endif %}
{% for pipe in components %}
-{% if pipe not in ["tagger", "morphologizer", "parser", "ner", "textcat", "textcat_multilabel", "entity_linker"] %}
+{% if pipe not in listener_components %}
{# Other components defined by the user: we just assume they're factories #}
[components.{{ pipe }}]
factory = "{{ pipe }}"
diff --git a/spacy/cli/templates/quickstart_training_recommendations.yml b/spacy/cli/templates/quickstart_training_recommendations.yml
index a7bf9b74a..4f214d22d 100644
--- a/spacy/cli/templates/quickstart_training_recommendations.yml
+++ b/spacy/cli/templates/quickstart_training_recommendations.yml
@@ -37,6 +37,15 @@ bn:
accuracy:
name: sagorsarker/bangla-bert-base
size_factor: 3
+ca:
+ word_vectors: null
+ transformer:
+ efficiency:
+ name: projecte-aina/roberta-base-ca-v2
+ size_factor: 3
+ accuracy:
+ name: projecte-aina/roberta-base-ca-v2
+ size_factor: 3
da:
word_vectors: da_core_news_lg
transformer:
@@ -271,4 +280,3 @@ zh:
accuracy:
name: bert-base-chinese
size_factor: 3
- has_letters: false
diff --git a/spacy/default_config.cfg b/spacy/default_config.cfg
index 86a72926e..694fb732f 100644
--- a/spacy/default_config.cfg
+++ b/spacy/default_config.cfg
@@ -90,6 +90,8 @@ dev_corpus = "corpora.dev"
train_corpus = "corpora.train"
# Optional callback before nlp object is saved to disk after training
before_to_disk = null
+# Optional callback that is invoked at the start of each training step
+before_update = null
[training.logger]
@loggers = "spacy.ConsoleLogger.v1"
diff --git a/spacy/displacy/__init__.py b/spacy/displacy/__init__.py
index 25d530c83..ea6bba2c9 100644
--- a/spacy/displacy/__init__.py
+++ b/spacy/displacy/__init__.py
@@ -7,10 +7,11 @@ USAGE: https://spacy.io/usage/visualizers
from typing import Union, Iterable, Optional, Dict, Any, Callable
import warnings
-from .render import DependencyRenderer, EntityRenderer
+from .render import DependencyRenderer, EntityRenderer, SpanRenderer
from ..tokens import Doc, Span
from ..errors import Errors, Warnings
from ..util import is_in_jupyter
+from ..util import find_available_port
_html = {}
@@ -36,7 +37,7 @@ def render(
jupyter (bool): Override Jupyter auto-detection.
options (dict): Visualiser-specific options, e.g. colors.
manual (bool): Don't parse `Doc` and instead expect a dict/list of dicts.
- RETURNS (str): Rendered HTML markup.
+ RETURNS (str): Rendered SVG or HTML markup.
DOCS: https://spacy.io/api/top-level#displacy.render
USAGE: https://spacy.io/usage/visualizers
@@ -44,6 +45,7 @@ def render(
factories = {
"dep": (DependencyRenderer, parse_deps),
"ent": (EntityRenderer, parse_ents),
+ "span": (SpanRenderer, parse_spans),
}
if style not in factories:
raise ValueError(Errors.E087.format(style=style))
@@ -55,6 +57,10 @@ def render(
renderer_func, converter = factories[style]
renderer = renderer_func(options=options)
parsed = [converter(doc, options) for doc in docs] if not manual else docs # type: ignore
+ if manual:
+ for doc in docs:
+ if isinstance(doc, dict) and "ents" in doc:
+ doc["ents"] = sorted(doc["ents"], key=lambda x: (x["start"], x["end"]))
_html["parsed"] = renderer.render(parsed, page=page, minify=minify).strip() # type: ignore
html = _html["parsed"]
if RENDER_WRAPPER is not None:
@@ -77,6 +83,7 @@ def serve(
manual: bool = False,
port: int = 5000,
host: str = "0.0.0.0",
+ auto_select_port: bool = False,
) -> None:
"""Serve displaCy visualisation.
@@ -88,12 +95,15 @@ def serve(
manual (bool): Don't parse `Doc` and instead expect a dict/list of dicts.
port (int): Port to serve visualisation.
host (str): Host to serve visualisation.
+ auto_select_port (bool): Automatically select a port if the specified port is in use.
DOCS: https://spacy.io/api/top-level#displacy.serve
USAGE: https://spacy.io/usage/visualizers
"""
from wsgiref import simple_server
+ port = find_available_port(port, host, auto_select_port)
+
if is_in_jupyter():
warnings.warn(Warnings.W011)
render(docs, style=style, page=page, minify=minify, options=options, manual=manual)
@@ -118,7 +128,8 @@ def app(environ, start_response):
def parse_deps(orig_doc: Doc, options: Dict[str, Any] = {}) -> Dict[str, Any]:
"""Generate dependency parse in {'words': [], 'arcs': []} format.
- doc (Doc): Document do parse.
+ orig_doc (Doc): Document to parse.
+ options (Dict[str, Any]): Dependency parse specific visualisation options.
RETURNS (dict): Generated dependency parse keyed by words and arcs.
"""
doc = Doc(orig_doc.vocab).from_bytes(
@@ -203,6 +214,43 @@ def parse_ents(doc: Doc, options: Dict[str, Any] = {}) -> Dict[str, Any]:
return {"text": doc.text, "ents": ents, "title": title, "settings": settings}
+def parse_spans(doc: Doc, options: Dict[str, Any] = {}) -> Dict[str, Any]:
+ """Generate spans in [{start_token: i, end_token: i, label: 'label'}] format.
+
+ doc (Doc): Document to parse.
+ options (Dict[str, any]): Span-specific visualisation options.
+ RETURNS (dict): Generated span types keyed by text (original text) and spans.
+ """
+ kb_url_template = options.get("kb_url_template", None)
+ spans_key = options.get("spans_key", "sc")
+ spans = [
+ {
+ "start": span.start_char,
+ "end": span.end_char,
+ "start_token": span.start,
+ "end_token": span.end,
+ "label": span.label_,
+ "kb_id": span.kb_id_ if span.kb_id_ else "",
+ "kb_url": kb_url_template.format(span.kb_id_) if kb_url_template else "#",
+ }
+ for span in doc.spans.get(spans_key, [])
+ ]
+ tokens = [token.text for token in doc]
+
+ if not spans:
+ keys = list(doc.spans.keys())
+ warnings.warn(Warnings.W117.format(spans_key=spans_key, keys=keys))
+ title = doc.user_data.get("title", None) if hasattr(doc, "user_data") else None
+ settings = get_doc_settings(doc)
+ return {
+ "text": doc.text,
+ "spans": spans,
+ "title": title,
+ "settings": settings,
+ "tokens": tokens,
+ }
+
+
def set_render_wrapper(func: Callable[[str], str]) -> None:
"""Set an optional wrapper function that is called around the generated
HTML markup on displacy.render. This can be used to allow integration into
diff --git a/spacy/displacy/render.py b/spacy/displacy/render.py
index a032d843b..f74222dc2 100644
--- a/spacy/displacy/render.py
+++ b/spacy/displacy/render.py
@@ -1,12 +1,15 @@
-from typing import Dict, Any, List, Optional, Union
+from typing import Any, Dict, List, Optional, Tuple, Union
import uuid
+import itertools
-from .templates import TPL_DEP_SVG, TPL_DEP_WORDS, TPL_DEP_WORDS_LEMMA, TPL_DEP_ARCS
-from .templates import TPL_ENT, TPL_ENT_RTL, TPL_FIGURE, TPL_TITLE, TPL_PAGE
-from .templates import TPL_ENTS, TPL_KB_LINK
-from ..util import minify_html, escape_html, registry
from ..errors import Errors
-
+from ..util import escape_html, minify_html, registry
+from .templates import TPL_DEP_ARCS, TPL_DEP_SVG, TPL_DEP_WORDS
+from .templates import TPL_DEP_WORDS_LEMMA, TPL_ENT, TPL_ENT_RTL, TPL_ENTS
+from .templates import TPL_FIGURE, TPL_KB_LINK, TPL_PAGE, TPL_SPAN
+from .templates import TPL_SPAN_RTL, TPL_SPAN_SLICE, TPL_SPAN_SLICE_RTL
+from .templates import TPL_SPAN_START, TPL_SPAN_START_RTL, TPL_SPANS
+from .templates import TPL_TITLE
DEFAULT_LANG = "en"
DEFAULT_DIR = "ltr"
@@ -33,6 +36,224 @@ DEFAULT_LABEL_COLORS = {
}
+class SpanRenderer:
+ """Render Spans as SVGs."""
+
+ style = "span"
+
+ def __init__(self, options: Dict[str, Any] = {}) -> None:
+ """Initialise span renderer
+
+ options (dict): Visualiser-specific options (colors, spans)
+ """
+ # Set up the colors and overall look
+ colors = dict(DEFAULT_LABEL_COLORS)
+ user_colors = registry.displacy_colors.get_all()
+ for user_color in user_colors.values():
+ if callable(user_color):
+ # Since this comes from the function registry, we want to make
+ # sure we support functions that *return* a dict of colors
+ user_color = user_color()
+ if not isinstance(user_color, dict):
+ raise ValueError(Errors.E925.format(obj=type(user_color)))
+ colors.update(user_color)
+ colors.update(options.get("colors", {}))
+ self.default_color = DEFAULT_ENTITY_COLOR
+ self.colors = {label.upper(): color for label, color in colors.items()}
+
+ # Set up how the text and labels will be rendered
+ self.direction = DEFAULT_DIR
+ self.lang = DEFAULT_LANG
+ # These values are in px
+ self.top_offset = options.get("top_offset", 40)
+ # This is how far under the top offset the span labels appear
+ self.span_label_offset = options.get("span_label_offset", 20)
+ self.offset_step = options.get("top_offset_step", 17)
+
+ # Set up which templates will be used
+ template = options.get("template")
+ if template:
+ self.span_template = template["span"]
+ self.span_slice_template = template["slice"]
+ self.span_start_template = template["start"]
+ else:
+ if self.direction == "rtl":
+ self.span_template = TPL_SPAN_RTL
+ self.span_slice_template = TPL_SPAN_SLICE_RTL
+ self.span_start_template = TPL_SPAN_START_RTL
+ else:
+ self.span_template = TPL_SPAN
+ self.span_slice_template = TPL_SPAN_SLICE
+ self.span_start_template = TPL_SPAN_START
+
+ def render(
+ self, parsed: List[Dict[str, Any]], page: bool = False, minify: bool = False
+ ) -> str:
+ """Render complete markup.
+
+ parsed (list): Dependency parses to render.
+ page (bool): Render parses wrapped as full HTML page.
+ minify (bool): Minify HTML markup.
+ RETURNS (str): Rendered SVG or HTML markup.
+ """
+ rendered = []
+ for i, p in enumerate(parsed):
+ if i == 0:
+ settings = p.get("settings", {})
+ self.direction = settings.get("direction", DEFAULT_DIR)
+ self.lang = settings.get("lang", DEFAULT_LANG)
+ rendered.append(self.render_spans(p["tokens"], p["spans"], p.get("title")))
+
+ if page:
+ docs = "".join([TPL_FIGURE.format(content=doc) for doc in rendered])
+ markup = TPL_PAGE.format(content=docs, lang=self.lang, dir=self.direction)
+ else:
+ markup = "".join(rendered)
+ if minify:
+ return minify_html(markup)
+ return markup
+
+ def render_spans(
+ self,
+ tokens: List[str],
+ spans: List[Dict[str, Any]],
+ title: Optional[str],
+ ) -> str:
+ """Render span types in text.
+
+ Spans are rendered per-token, this means that for each token, we check if it's part
+ of a span slice (a member of a span type) or a span start (the starting token of a
+ given span type).
+
+ tokens (list): Individual tokens in the text
+ spans (list): Individual entity spans and their start, end, label, kb_id and kb_url.
+ title (str / None): Document title set in Doc.user_data['title'].
+ """
+ per_token_info = []
+ # we must sort so that we can correctly describe when spans need to "stack"
+ # which is determined by their start token, then span length (longer spans on top),
+ # then break any remaining ties with the span label
+ spans = sorted(
+ spans,
+ key=lambda s: (
+ s["start_token"],
+ -(s["end_token"] - s["start_token"]),
+ s["label"],
+ ),
+ )
+ for s in spans:
+ # this is the vertical 'slot' that the span will be rendered in
+ # vertical_position = span_label_offset + (offset_step * (slot - 1))
+ s["render_slot"] = 0
+ for idx, token in enumerate(tokens):
+ # Identify if a token belongs to a Span (and which) and if it's a
+ # start token of said Span. We'll use this for the final HTML render
+ token_markup: Dict[str, Any] = {}
+ token_markup["text"] = token
+ concurrent_spans = 0
+ entities = []
+ for span in spans:
+ ent = {}
+ if span["start_token"] <= idx < span["end_token"]:
+ concurrent_spans += 1
+ span_start = idx == span["start_token"]
+ ent["label"] = span["label"]
+ ent["is_start"] = span_start
+ if span_start:
+ # When the span starts, we need to know how many other
+ # spans are on the 'span stack' and will be rendered.
+ # This value becomes the vertical render slot for this entire span
+ span["render_slot"] = concurrent_spans
+ ent["render_slot"] = span["render_slot"]
+ kb_id = span.get("kb_id", "")
+ kb_url = span.get("kb_url", "#")
+ ent["kb_link"] = (
+ TPL_KB_LINK.format(kb_id=kb_id, kb_url=kb_url) if kb_id else ""
+ )
+ entities.append(ent)
+ else:
+ # We don't specifically need to do this since we loop
+ # over tokens and spans sorted by their start_token,
+ # so we'll never use a span again after the last token it appears in,
+ # but if we were to use these spans again we'd want to make sure
+ # this value was reset correctly.
+ span["render_slot"] = 0
+ token_markup["entities"] = entities
+ per_token_info.append(token_markup)
+ markup = self._render_markup(per_token_info)
+ markup = TPL_SPANS.format(content=markup, dir=self.direction)
+ if title:
+ markup = TPL_TITLE.format(title=title) + markup
+ return markup
+
+ def _render_markup(self, per_token_info: List[Dict[str, Any]]) -> str:
+ """Render the markup from per-token information"""
+ markup = ""
+ for token in per_token_info:
+ entities = sorted(token["entities"], key=lambda d: d["render_slot"])
+ # Whitespace tokens disrupt the vertical space (no line height) so that the
+ # span indicators get misaligned. We don't render them as individual
+ # tokens anyway, so we'll just not display a span indicator either.
+ is_whitespace = token["text"].strip() == ""
+ if entities and not is_whitespace:
+ slices = self._get_span_slices(token["entities"])
+ starts = self._get_span_starts(token["entities"])
+ total_height = (
+ self.top_offset
+ + self.span_label_offset
+ + (self.offset_step * (len(entities) - 1))
+ )
+ markup += self.span_template.format(
+ text=token["text"],
+ span_slices=slices,
+ span_starts=starts,
+ total_height=total_height,
+ )
+ else:
+ markup += escape_html(token["text"] + " ")
+ return markup
+
+ def _get_span_slices(self, entities: List[Dict]) -> str:
+ """Get the rendered markup of all Span slices"""
+ span_slices = []
+ for entity in entities:
+ # rather than iterate over multiples of offset_step, we use entity['render_slot']
+ # to determine the vertical position, since that tells where
+ # the span starts vertically so we can extend it horizontally,
+ # past other spans that might have already ended
+ color = self.colors.get(entity["label"].upper(), self.default_color)
+ top_offset = self.top_offset + (
+ self.offset_step * (entity["render_slot"] - 1)
+ )
+ span_slice = self.span_slice_template.format(
+ bg=color,
+ top_offset=top_offset,
+ )
+ span_slices.append(span_slice)
+ return "".join(span_slices)
+
+ def _get_span_starts(self, entities: List[Dict]) -> str:
+ """Get the rendered markup of all Span start tokens"""
+ span_starts = []
+ for entity in entities:
+ color = self.colors.get(entity["label"].upper(), self.default_color)
+ top_offset = self.top_offset + (
+ self.offset_step * (entity["render_slot"] - 1)
+ )
+ span_start = (
+ self.span_start_template.format(
+ bg=color,
+ top_offset=top_offset,
+ label=entity["label"],
+ kb_link=entity["kb_link"],
+ )
+ if entity["is_start"]
+ else ""
+ )
+ span_starts.append(span_start)
+ return "".join(span_starts)
+
+
class DependencyRenderer:
"""Render dependency parses as SVGs."""
@@ -105,7 +326,7 @@ class DependencyRenderer:
RETURNS (str): Rendered SVG markup.
"""
self.levels = self.get_levels(arcs)
- self.highest_level = len(self.levels)
+ self.highest_level = max(self.levels.values(), default=0)
self.offset_y = self.distance / 2 * self.highest_level + self.arrow_stroke
self.width = self.offset_x + len(words) * self.distance
self.height = self.offset_y + 3 * self.word_spacing
@@ -165,7 +386,7 @@ class DependencyRenderer:
if start < 0 or end < 0:
error_args = dict(start=start, end=end, label=label, dir=direction)
raise ValueError(Errors.E157.format(**error_args))
- level = self.levels.index(end - start) + 1
+ level = self.levels[(start, end, label)]
x_start = self.offset_x + start * self.distance + self.arrow_spacing
if self.direction == "rtl":
x_start = self.width - x_start
@@ -181,7 +402,7 @@ class DependencyRenderer:
y_curve = self.offset_y - level * self.distance / 2
if self.compact:
y_curve = self.offset_y - level * self.distance / 6
- if y_curve == 0 and len(self.levels) > 5:
+ if y_curve == 0 and max(self.levels.values(), default=0) > 5:
y_curve = -self.distance
arrowhead = self.get_arrowhead(direction, x_start, y, x_end)
arc = self.get_arc(x_start, y, y_curve, x_end)
@@ -225,15 +446,23 @@ class DependencyRenderer:
p1, p2, p3 = (end, end + self.arrow_width - 2, end - self.arrow_width + 2)
return f"M{p1},{y + 2} L{p2},{y - self.arrow_width} {p3},{y - self.arrow_width}"
- def get_levels(self, arcs: List[Dict[str, Any]]) -> List[int]:
+ def get_levels(self, arcs: List[Dict[str, Any]]) -> Dict[Tuple[int, int, str], int]:
"""Calculate available arc height "levels".
Used to calculate arrow heights dynamically and without wasting space.
args (list): Individual arcs and their start, end, direction and label.
- RETURNS (list): Arc levels sorted from lowest to highest.
+ RETURNS (dict): Arc levels keyed by (start, end, label).
"""
- levels = set(map(lambda arc: arc["end"] - arc["start"], arcs))
- return sorted(list(levels))
+ arcs = [dict(t) for t in {tuple(sorted(arc.items())) for arc in arcs}]
+ length = max([arc["end"] for arc in arcs], default=0)
+ max_level = [0] * length
+ levels = {}
+ for arc in sorted(arcs, key=lambda arc: arc["end"] - arc["start"]):
+ level = max(max_level[arc["start"] : arc["end"]]) + 1
+ for i in range(arc["start"], arc["end"]):
+ max_level[i] = level
+ levels[(arc["start"], arc["end"], arc["label"])] = level
+ return levels
class EntityRenderer:
@@ -242,7 +471,7 @@ class EntityRenderer:
style = "ent"
def __init__(self, options: Dict[str, Any] = {}) -> None:
- """Initialise dependency renderer.
+ """Initialise entity renderer.
options (dict): Visualiser-specific options (colors, ents)
"""
@@ -281,7 +510,7 @@ class EntityRenderer:
parsed (list): Dependency parses to render.
page (bool): Render parses wrapped as full HTML page.
minify (bool): Minify HTML markup.
- RETURNS (str): Rendered HTML markup.
+ RETURNS (str): Rendered SVG or HTML markup.
"""
rendered = []
for i, p in enumerate(parsed):
diff --git a/spacy/displacy/templates.py b/spacy/displacy/templates.py
index e7d3d4266..40f5376b1 100644
--- a/spacy/displacy/templates.py
+++ b/spacy/displacy/templates.py
@@ -62,6 +62,55 @@ TPL_ENT_RTL = """
"""
+TPL_SPANS = """
+
{content}
+"""
+
+TPL_SPAN = """
+
+ {text}
+ {span_slices}
+ {span_starts}
+
+"""
+
+TPL_SPAN_SLICE = """
+
+
+"""
+
+
+TPL_SPAN_START = """
+
+
+ {label}{kb_link}
+
+
+
+"""
+
+TPL_SPAN_RTL = """
+
+ {text}
+ {span_slices}
+ {span_starts}
+
+"""
+
+TPL_SPAN_SLICE_RTL = """
+
+
+"""
+
+TPL_SPAN_START_RTL = """
+
+
+ {label}{kb_link}
+
+
+"""
+
+
# Important: this needs to start with a space!
TPL_KB_LINK = """
{kb_id}
diff --git a/spacy/errors.py b/spacy/errors.py
index 5399e489b..d143e341c 100644
--- a/spacy/errors.py
+++ b/spacy/errors.py
@@ -1,4 +1,5 @@
import warnings
+from .compat import Literal
class ErrorsWithCodes(type):
@@ -15,8 +16,8 @@ def setup_default_warnings():
filter_warning("ignore", error_msg="numpy.dtype size changed") # noqa
filter_warning("ignore", error_msg="numpy.ufunc size changed") # noqa
- # warn about entity_ruler & matcher having no patterns only once
- for pipe in ["matcher", "entity_ruler"]:
+ # warn about entity_ruler, span_ruler & matcher having no patterns only once
+ for pipe in ["matcher", "entity_ruler", "span_ruler"]:
filter_warning("once", error_msg=Warnings.W036.format(name=pipe))
# warn once about lemmatizer without required POS
@@ -26,7 +27,10 @@ def setup_default_warnings():
filter_warning("once", error_msg="[W114]")
-def filter_warning(action: str, error_msg: str):
+def filter_warning(
+ action: Literal["default", "error", "ignore", "always", "module", "once"],
+ error_msg: str,
+):
"""Customize how spaCy should handle a certain warning.
error_msg (str): e.g. "W006", or a full error message
@@ -192,6 +196,25 @@ class Warnings(metaclass=ErrorsWithCodes):
W115 = ("Skipping {method}: the floret vector table cannot be modified. "
"Vectors are calculated from character ngrams.")
W116 = ("Unable to clean attribute '{attr}'.")
+ W117 = ("No spans to visualize found in Doc object with spans_key: '{spans_key}'. If this is "
+ "surprising to you, make sure the Doc was processed using a model "
+ "that supports span categorization, and check the `doc.spans[spans_key]` "
+ "property manually if necessary.\n\nAvailable keys: {keys}")
+ W118 = ("Term '{term}' not found in glossary. It may however be explained in documentation "
+ "for the corpora used to train the language. Please check "
+ "`nlp.meta[\"sources\"]` for any relevant links.")
+ W119 = ("Overriding pipe name in `config` is not supported. Ignoring override '{name_in_config}'.")
+ W120 = ("Unable to load all spans in Doc.spans: more than one span group "
+ "with the name '{group_name}' was found in the saved spans data. "
+ "Only the last span group will be loaded under "
+ "Doc.spans['{group_name}']. Skipping span group with values: "
+ "{group_values}")
+ W121 = ("Attempting to trace non-existent method '{method}' in pipe '{pipe}'")
+ W122 = ("Couldn't trace method '{method}' in pipe '{pipe}'. This can happen if the pipe class "
+ "is a Cython extension type.")
+ W123 = ("Argument `enable` with value {enable} does not contain all values specified in the config option "
+ "`enabled` ({enabled}). Be aware that this might affect other components in your pipeline.")
+ W124 = ("{host}:{port} is already in use, using the nearest available port {serve_port} as an alternative.")
class Errors(metaclass=ErrorsWithCodes):
@@ -210,8 +233,9 @@ class Errors(metaclass=ErrorsWithCodes):
"initialized component.")
E004 = ("Can't set up pipeline component: a factory for '{name}' already "
"exists. Existing factory: {func}. New factory: {new_func}")
- E005 = ("Pipeline component '{name}' returned None. If you're using a "
- "custom component, maybe you forgot to return the processed Doc?")
+ E005 = ("Pipeline component '{name}' returned {returned_type} instead of a "
+ "Doc. If you're using a custom component, maybe you forgot to "
+ "return the processed Doc?")
E006 = ("Invalid constraints for adding pipeline component. You can only "
"set one of the following: before (component name or index), "
"after (component name or index), first (True) or last (True). "
@@ -322,6 +346,11 @@ class Errors(metaclass=ErrorsWithCodes):
"clear the existing vectors and resize the table.")
E074 = ("Error interpreting compiled match pattern: patterns are expected "
"to end with the attribute {attr}. Got: {bad_attr}.")
+ E079 = ("Error computing states in beam: number of predicted beams "
+ "({pbeams}) does not equal number of gold beams ({gbeams}).")
+ E080 = ("Duplicate state found in beam: {key}.")
+ E081 = ("Error getting gradient in beam: number of histories ({n_hist}) "
+ "does not equal number of losses ({losses}).")
E082 = ("Error deprojectivizing parse: number of heads ({n_heads}), "
"projective heads ({n_proj_heads}) and labels ({n_labels}) do not "
"match.")
@@ -369,7 +398,7 @@ class Errors(metaclass=ErrorsWithCodes):
"consider using doc.spans instead.")
E106 = ("Can't find `doc._.{attr}` attribute specified in the underscore "
"settings: {opts}")
- E107 = ("Value of `doc._.{attr}` is not JSON-serializable: {value}")
+ E107 = ("Value of custom attribute `{attr}` is not JSON-serializable: {value}")
E109 = ("Component '{name}' could not be run. Did you forget to "
"call `initialize()`?")
E110 = ("Invalid displaCy render wrapper. Expected callable, got: {obj}")
@@ -437,10 +466,10 @@ class Errors(metaclass=ErrorsWithCodes):
"same, but found '{nlp}' and '{vocab}' respectively.")
E152 = ("The attribute {attr} is not supported for token patterns. "
"Please use the option `validate=True` with the Matcher, PhraseMatcher, "
- "or EntityRuler for more details.")
+ "EntityRuler or AttributeRuler for more details.")
E153 = ("The value type {vtype} is not supported for token patterns. "
"Please use the option validate=True with Matcher, PhraseMatcher, "
- "or EntityRuler for more details.")
+ "EntityRuler or AttributeRuler for more details.")
E154 = ("One of the attributes or values is not supported for token "
"patterns. Please use the option `validate=True` with the Matcher, "
"PhraseMatcher, or EntityRuler for more details.")
@@ -515,15 +544,28 @@ class Errors(metaclass=ErrorsWithCodes):
E198 = ("Unable to return {n} most similar vectors for the current vectors "
"table, which contains {n_rows} vectors.")
E199 = ("Unable to merge 0-length span at `doc[{start}:{end}]`.")
- E200 = ("Can't yet set {attr} from Span. Vote for this feature on the "
- "issue tracker: http://github.com/explosion/spaCy/issues")
+ E200 = ("Can't set {attr} from Span.")
E202 = ("Unsupported {name} mode '{mode}'. Supported modes: {modes}.")
+ E203 = ("If the {name} embedding layer is not updated "
+ "during training, make sure to include it in 'annotating components'")
# New errors added in v3.x
+ E851 = ("The 'textcat' component labels should only have values of 0 or 1, "
+ "but found value of '{val}'.")
+ E852 = ("The tar file pulled from the remote attempted an unsafe path "
+ "traversal.")
+ E853 = ("Unsupported component factory name '{name}'. The character '.' is "
+ "not permitted in factory names.")
+ E854 = ("Unable to set doc.ents. Check that the 'ents_filter' does not "
+ "permit overlapping spans.")
+ E855 = ("Invalid {obj}: {obj} is not from the same doc.")
+ E856 = ("Error accessing span at position {i}: out of bounds in span group "
+ "of length {length}.")
+ E857 = ("Entry '{name}' not found in edit tree lemmatizer labels.")
E858 = ("The {mode} vector table does not support this operation. "
"{alternative}")
E859 = ("The floret vector table cannot be modified.")
- E860 = ("Can't truncate fasttext-bloom vectors.")
+ E860 = ("Can't truncate floret vectors.")
E861 = ("No 'keys' should be provided when initializing floret vectors "
"with 'minn' and 'maxn'.")
E862 = ("'hash_count' must be between 1-4 for floret vectors.")
@@ -679,11 +721,11 @@ class Errors(metaclass=ErrorsWithCodes):
"need to modify the pipeline, use the built-in methods like "
"`nlp.add_pipe`, `nlp.remove_pipe`, `nlp.disable_pipe` or "
"`nlp.enable_pipe` instead.")
- E927 = ("Can't write to frozen list Maybe you're trying to modify a computed "
+ E927 = ("Can't write to frozen list. Maybe you're trying to modify a computed "
"property or default function argument?")
- E928 = ("A KnowledgeBase can only be serialized to/from from a directory, "
+ E928 = ("An InMemoryLookupKB can only be serialized to/from from a directory, "
"but the provided argument {loc} points to a file.")
- E929 = ("Couldn't read KnowledgeBase from {loc}. The path does not seem to exist.")
+ E929 = ("Couldn't read InMemoryLookupKB from {loc}. The path does not seem to exist.")
E930 = ("Received invalid get_examples callback in `{method}`. "
"Expected function that returns an iterable of Example objects but "
"got: {obj}")
@@ -887,11 +929,46 @@ class Errors(metaclass=ErrorsWithCodes):
E1022 = ("Words must be of type str or int, but input is of type '{wtype}'")
E1023 = ("Couldn't read EntityRuler from the {path}. This file doesn't "
"exist.")
- E1024 = ("A pattern with ID \"{ent_id}\" is not present in EntityRuler "
- "patterns.")
+ E1024 = ("A pattern with {attr_type} '{label}' is not present in "
+ "'{component}' patterns.")
E1025 = ("Cannot intify the value '{value}' as an IOB string. The only "
"supported values are: 'I', 'O', 'B' and ''")
-
+ E1026 = ("Edit tree has an invalid format:\n{errors}")
+ E1027 = ("AlignmentArray only supports slicing with a step of 1.")
+ E1028 = ("AlignmentArray only supports indexing using an int or a slice.")
+ E1029 = ("Edit tree cannot be applied to form.")
+ E1030 = ("Edit tree identifier out of range.")
+ E1031 = ("Could not find gold transition - see logs above.")
+ E1032 = ("`{var}` should not be {forbidden}, but received {value}.")
+ E1033 = ("Dimension {name} invalid -- only nO, nF, nP")
+ E1034 = ("Node index {i} out of bounds ({length})")
+ E1035 = ("Token index {i} out of bounds ({length})")
+ E1036 = ("Cannot index into NoneNode")
+ E1037 = ("Invalid attribute value '{attr}'.")
+ E1038 = ("Invalid JSON input: {message}")
+ E1039 = ("The {obj} start or end annotations (start: {start}, end: {end}) "
+ "could not be aligned to token boundaries.")
+ E1040 = ("Doc.from_json requires all tokens to have the same attributes. "
+ "Some tokens do not contain annotation for: {partial_attrs}")
+ E1041 = ("Expected a string, Doc, or bytes as input, but got: {type}")
+ E1042 = ("`enable={enable}` and `disable={disable}` are inconsistent with each other.\nIf you only passed "
+ "one of `enable` or `disable`, the other argument is specified in your pipeline's configuration.\nIn that "
+ "case pass an empty list for the previously not specified argument to avoid this error.")
+ E1043 = ("Expected None or a value in range [{range_start}, {range_end}] for entity linker threshold, but got "
+ "{value}.")
+ E1044 = ("Expected `candidates_batch_size` to be >= 1, but got: {value}")
+ E1045 = ("Encountered {parent} subclass without `{parent}.{method}` "
+ "method in '{name}'. If you want to use this method, make "
+ "sure it's overwritten on the subclass.")
+ E1046 = ("{cls_name} is an abstract class and cannot be instantiated. If you are looking for spaCy's default "
+ "knowledge base, use `InMemoryLookupKB`.")
+ E1047 = ("`find_threshold()` only supports components with a `scorer` attribute.")
+ E1048 = ("Got '{unexpected}' as console progress bar type, but expected one of the following: {expected}")
+ E1049 = ("No available port found for displaCy on host {host}. Please specify an available port "
+ "with `displacy.serve(doc, port=port)`")
+ E1050 = ("Port {port} is already in use. Please specify an available port with `displacy.serve(doc, port=port)` "
+ "or use `auto_switch_port=True` to pick an available port automatically.")
+
# Deprecated model shortcuts, only used in errors and warnings
OLD_MODEL_SHORTCUTS = {
diff --git a/spacy/glossary.py b/spacy/glossary.py
index 57254330f..d2240fbba 100644
--- a/spacy/glossary.py
+++ b/spacy/glossary.py
@@ -1,3 +1,7 @@
+import warnings
+from .errors import Warnings
+
+
def explain(term):
"""Get a description for a given POS tag, dependency label or entity type.
@@ -11,6 +15,8 @@ def explain(term):
"""
if term in GLOSSARY:
return GLOSSARY[term]
+ else:
+ warnings.warn(Warnings.W118.format(term=term))
GLOSSARY = {
@@ -267,6 +273,7 @@ GLOSSARY = {
"relcl": "relative clause modifier",
"reparandum": "overridden disfluency",
"root": "root",
+ "ROOT": "root",
"vocative": "vocative",
"xcomp": "open clausal complement",
# Dependency labels (German)
diff --git a/spacy/kb/__init__.py b/spacy/kb/__init__.py
new file mode 100644
index 000000000..1d70a9b34
--- /dev/null
+++ b/spacy/kb/__init__.py
@@ -0,0 +1,3 @@
+from .kb import KnowledgeBase
+from .kb_in_memory import InMemoryLookupKB
+from .candidate import Candidate, get_candidates, get_candidates_batch
diff --git a/spacy/kb/candidate.pxd b/spacy/kb/candidate.pxd
new file mode 100644
index 000000000..942ce9dd0
--- /dev/null
+++ b/spacy/kb/candidate.pxd
@@ -0,0 +1,12 @@
+from .kb cimport KnowledgeBase
+from libcpp.vector cimport vector
+from ..typedefs cimport hash_t
+
+# Object used by the Entity Linker that summarizes one entity-alias candidate combination.
+cdef class Candidate:
+ cdef readonly KnowledgeBase kb
+ cdef hash_t entity_hash
+ cdef float entity_freq
+ cdef vector[float] entity_vector
+ cdef hash_t alias_hash
+ cdef float prior_prob
diff --git a/spacy/kb/candidate.pyx b/spacy/kb/candidate.pyx
new file mode 100644
index 000000000..c89efeb03
--- /dev/null
+++ b/spacy/kb/candidate.pyx
@@ -0,0 +1,74 @@
+# cython: infer_types=True, profile=True
+
+from typing import Iterable
+from .kb cimport KnowledgeBase
+from ..tokens import Span
+
+cdef class Candidate:
+ """A `Candidate` object refers to a textual mention (`alias`) that may or may not be resolved
+ to a specific `entity` from a Knowledge Base. This will be used as input for the entity linking
+ algorithm which will disambiguate the various candidates to the correct one.
+ Each candidate (alias, entity) pair is assigned a certain prior probability.
+
+ DOCS: https://spacy.io/api/kb/#candidate-init
+ """
+
+ def __init__(self, KnowledgeBase kb, entity_hash, entity_freq, entity_vector, alias_hash, prior_prob):
+ self.kb = kb
+ self.entity_hash = entity_hash
+ self.entity_freq = entity_freq
+ self.entity_vector = entity_vector
+ self.alias_hash = alias_hash
+ self.prior_prob = prior_prob
+
+ @property
+ def entity(self) -> int:
+ """RETURNS (uint64): hash of the entity's KB ID/name"""
+ return self.entity_hash
+
+ @property
+ def entity_(self) -> str:
+ """RETURNS (str): ID/name of this entity in the KB"""
+ return self.kb.vocab.strings[self.entity_hash]
+
+ @property
+ def alias(self) -> int:
+ """RETURNS (uint64): hash of the alias"""
+ return self.alias_hash
+
+ @property
+ def alias_(self) -> str:
+ """RETURNS (str): ID of the original alias"""
+ return self.kb.vocab.strings[self.alias_hash]
+
+ @property
+ def entity_freq(self) -> float:
+ return self.entity_freq
+
+ @property
+ def entity_vector(self) -> Iterable[float]:
+ return self.entity_vector
+
+ @property
+ def prior_prob(self) -> float:
+ return self.prior_prob
+
+
+def get_candidates(kb: KnowledgeBase, mention: Span) -> Iterable[Candidate]:
+ """
+ Return candidate entities for a given mention and fetching appropriate entries from the index.
+ kb (KnowledgeBase): Knowledge base to query.
+ mention (Span): Entity mention for which to identify candidates.
+ RETURNS (Iterable[Candidate]): Identified candidates.
+ """
+ return kb.get_candidates(mention)
+
+
+def get_candidates_batch(kb: KnowledgeBase, mentions: Iterable[Span]) -> Iterable[Iterable[Candidate]]:
+ """
+ Return candidate entities for the given mentions and fetching appropriate entries from the index.
+ kb (KnowledgeBase): Knowledge base to query.
+ mention (Iterable[Span]): Entity mentions for which to identify candidates.
+ RETURNS (Iterable[Iterable[Candidate]]): Identified candidates.
+ """
+ return kb.get_candidates_batch(mentions)
diff --git a/spacy/kb/kb.pxd b/spacy/kb/kb.pxd
new file mode 100644
index 000000000..1adeef8ae
--- /dev/null
+++ b/spacy/kb/kb.pxd
@@ -0,0 +1,10 @@
+"""Knowledge-base for entity or concept linking."""
+
+from cymem.cymem cimport Pool
+from libc.stdint cimport int64_t
+from ..vocab cimport Vocab
+
+cdef class KnowledgeBase:
+ cdef Pool mem
+ cdef readonly Vocab vocab
+ cdef readonly int64_t entity_vector_length
diff --git a/spacy/kb/kb.pyx b/spacy/kb/kb.pyx
new file mode 100644
index 000000000..ce4bc0138
--- /dev/null
+++ b/spacy/kb/kb.pyx
@@ -0,0 +1,108 @@
+# cython: infer_types=True, profile=True
+
+from pathlib import Path
+from typing import Iterable, Tuple, Union
+from cymem.cymem cimport Pool
+
+from .candidate import Candidate
+from ..tokens import Span
+from ..util import SimpleFrozenList
+from ..errors import Errors
+
+
+cdef class KnowledgeBase:
+ """A `KnowledgeBase` instance stores unique identifiers for entities and their textual aliases,
+ to support entity linking of named entities to real-world concepts.
+ This is an abstract class and requires its operations to be implemented.
+
+ DOCS: https://spacy.io/api/kb
+ """
+
+ def __init__(self, vocab: Vocab, entity_vector_length: int):
+ """Create a KnowledgeBase."""
+ # Make sure abstract KB is not instantiated.
+ if self.__class__ == KnowledgeBase:
+ raise TypeError(
+ Errors.E1046.format(cls_name=self.__class__.__name__)
+ )
+
+ self.vocab = vocab
+ self.entity_vector_length = entity_vector_length
+ self.mem = Pool()
+
+ def get_candidates_batch(self, mentions: Iterable[Span]) -> Iterable[Iterable[Candidate]]:
+ """
+ Return candidate entities for specified texts. Each candidate defines the entity, the original alias,
+ and the prior probability of that alias resolving to that entity.
+ If no candidate is found for a given text, an empty list is returned.
+ mentions (Iterable[Span]): Mentions for which to get candidates.
+ RETURNS (Iterable[Iterable[Candidate]]): Identified candidates.
+ """
+ return [self.get_candidates(span) for span in mentions]
+
+ def get_candidates(self, mention: Span) -> Iterable[Candidate]:
+ """
+ Return candidate entities for specified text. Each candidate defines the entity, the original alias,
+ and the prior probability of that alias resolving to that entity.
+ If the no candidate is found for a given text, an empty list is returned.
+ mention (Span): Mention for which to get candidates.
+ RETURNS (Iterable[Candidate]): Identified candidates.
+ """
+ raise NotImplementedError(
+ Errors.E1045.format(parent="KnowledgeBase", method="get_candidates", name=self.__name__)
+ )
+
+ def get_vectors(self, entities: Iterable[str]) -> Iterable[Iterable[float]]:
+ """
+ Return vectors for entities.
+ entity (str): Entity name/ID.
+ RETURNS (Iterable[Iterable[float]]): Vectors for specified entities.
+ """
+ return [self.get_vector(entity) for entity in entities]
+
+ def get_vector(self, str entity) -> Iterable[float]:
+ """
+ Return vector for entity.
+ entity (str): Entity name/ID.
+ RETURNS (Iterable[float]): Vector for specified entity.
+ """
+ raise NotImplementedError(
+ Errors.E1045.format(parent="KnowledgeBase", method="get_vector", name=self.__name__)
+ )
+
+ def to_bytes(self, **kwargs) -> bytes:
+ """Serialize the current state to a binary string.
+ RETURNS (bytes): Current state as binary string.
+ """
+ raise NotImplementedError(
+ Errors.E1045.format(parent="KnowledgeBase", method="to_bytes", name=self.__name__)
+ )
+
+ def from_bytes(self, bytes_data: bytes, *, exclude: Tuple[str] = tuple()):
+ """Load state from a binary string.
+ bytes_data (bytes): KB state.
+ exclude (Tuple[str]): Properties to exclude when restoring KB.
+ """
+ raise NotImplementedError(
+ Errors.E1045.format(parent="KnowledgeBase", method="from_bytes", name=self.__name__)
+ )
+
+ def to_disk(self, path: Union[str, Path], exclude: Iterable[str] = SimpleFrozenList()) -> None:
+ """
+ Write KnowledgeBase content to disk.
+ path (Union[str, Path]): Target file path.
+ exclude (Iterable[str]): List of components to exclude.
+ """
+ raise NotImplementedError(
+ Errors.E1045.format(parent="KnowledgeBase", method="to_disk", name=self.__name__)
+ )
+
+ def from_disk(self, path: Union[str, Path], exclude: Iterable[str] = SimpleFrozenList()) -> None:
+ """
+ Load KnowledgeBase content from disk.
+ path (Union[str, Path]): Target file path.
+ exclude (Iterable[str]): List of components to exclude.
+ """
+ raise NotImplementedError(
+ Errors.E1045.format(parent="KnowledgeBase", method="from_disk", name=self.__name__)
+ )
diff --git a/spacy/kb.pxd b/spacy/kb/kb_in_memory.pxd
similarity index 92%
rename from spacy/kb.pxd
rename to spacy/kb/kb_in_memory.pxd
index a823dbe1e..825a6bde9 100644
--- a/spacy/kb.pxd
+++ b/spacy/kb/kb_in_memory.pxd
@@ -1,14 +1,12 @@
"""Knowledge-base for entity or concept linking."""
-from cymem.cymem cimport Pool
from preshed.maps cimport PreshMap
from libcpp.vector cimport vector
from libc.stdint cimport int32_t, int64_t
from libc.stdio cimport FILE
-from .vocab cimport Vocab
-from .typedefs cimport hash_t
-from .structs cimport KBEntryC, AliasC
-
+from ..typedefs cimport hash_t
+from ..structs cimport KBEntryC, AliasC
+from .kb cimport KnowledgeBase
ctypedef vector[KBEntryC] entry_vec
ctypedef vector[AliasC] alias_vec
@@ -16,21 +14,7 @@ ctypedef vector[float] float_vec
ctypedef vector[float_vec] float_matrix
-# Object used by the Entity Linker that summarizes one entity-alias candidate combination.
-cdef class Candidate:
- cdef readonly KnowledgeBase kb
- cdef hash_t entity_hash
- cdef float entity_freq
- cdef vector[float] entity_vector
- cdef hash_t alias_hash
- cdef float prior_prob
-
-
-cdef class KnowledgeBase:
- cdef Pool mem
- cdef readonly Vocab vocab
- cdef int64_t entity_vector_length
-
+cdef class InMemoryLookupKB(KnowledgeBase):
# This maps 64bit keys (hash of unique entity string)
# to 64bit values (position of the _KBEntryC struct in the _entries vector).
# The PreshMap is pretty space efficient, as it uses open addressing. So
diff --git a/spacy/kb.pyx b/spacy/kb/kb_in_memory.pyx
similarity index 88%
rename from spacy/kb.pyx
rename to spacy/kb/kb_in_memory.pyx
index 9a765c8e4..edba523cf 100644
--- a/spacy/kb.pyx
+++ b/spacy/kb/kb_in_memory.pyx
@@ -1,8 +1,7 @@
# cython: infer_types=True, profile=True
-from typing import Iterator, Iterable, Callable, Dict, Any
+from typing import Iterable, Callable, Dict, Any, Union
import srsly
-from cymem.cymem cimport Pool
from preshed.maps cimport PreshMap
from cpython.exc cimport PyErr_SetFromErrno
from libc.stdio cimport fopen, fclose, fread, fwrite, feof, fseek
@@ -12,103 +11,41 @@ from libcpp.vector cimport vector
from pathlib import Path
import warnings
-from .typedefs cimport hash_t
-from .errors import Errors, Warnings
-from . import util
-from .util import SimpleFrozenList, ensure_path
-
-cdef class Candidate:
- """A `Candidate` object refers to a textual mention (`alias`) that may or may not be resolved
- to a specific `entity` from a Knowledge Base. This will be used as input for the entity linking
- algorithm which will disambiguate the various candidates to the correct one.
- Each candidate (alias, entity) pair is assigned to a certain prior probability.
-
- DOCS: https://spacy.io/api/kb/#candidate_init
- """
-
- def __init__(self, KnowledgeBase kb, entity_hash, entity_freq, entity_vector, alias_hash, prior_prob):
- self.kb = kb
- self.entity_hash = entity_hash
- self.entity_freq = entity_freq
- self.entity_vector = entity_vector
- self.alias_hash = alias_hash
- self.prior_prob = prior_prob
-
- @property
- def entity(self):
- """RETURNS (uint64): hash of the entity's KB ID/name"""
- return self.entity_hash
-
- @property
- def entity_(self):
- """RETURNS (str): ID/name of this entity in the KB"""
- return self.kb.vocab.strings[self.entity_hash]
-
- @property
- def alias(self):
- """RETURNS (uint64): hash of the alias"""
- return self.alias_hash
-
- @property
- def alias_(self):
- """RETURNS (str): ID of the original alias"""
- return self.kb.vocab.strings[self.alias_hash]
-
- @property
- def entity_freq(self):
- return self.entity_freq
-
- @property
- def entity_vector(self):
- return self.entity_vector
-
- @property
- def prior_prob(self):
- return self.prior_prob
+from ..tokens import Span
+from ..typedefs cimport hash_t
+from ..errors import Errors, Warnings
+from .. import util
+from ..util import SimpleFrozenList, ensure_path
+from ..vocab cimport Vocab
+from .kb cimport KnowledgeBase
+from .candidate import Candidate as Candidate
-def get_candidates(KnowledgeBase kb, span) -> Iterator[Candidate]:
- """
- Return candidate entities for a given span by using the text of the span as the alias
- and fetching appropriate entries from the index.
- This particular function is optimized to work with the built-in KB functionality,
- but any other custom candidate generation method can be used in combination with the KB as well.
- """
- return kb.get_alias_candidates(span.text)
-
-
-cdef class KnowledgeBase:
- """A `KnowledgeBase` instance stores unique identifiers for entities and their textual aliases,
+cdef class InMemoryLookupKB(KnowledgeBase):
+ """An `InMemoryLookupKB` instance stores unique identifiers for entities and their textual aliases,
to support entity linking of named entities to real-world concepts.
- DOCS: https://spacy.io/api/kb
+ DOCS: https://spacy.io/api/inmemorylookupkb
"""
def __init__(self, Vocab vocab, entity_vector_length):
- """Create a KnowledgeBase."""
- self.mem = Pool()
- self.entity_vector_length = entity_vector_length
+ """Create an InMemoryLookupKB."""
+ super().__init__(vocab, entity_vector_length)
self._entry_index = PreshMap()
self._alias_index = PreshMap()
- self.vocab = vocab
self._create_empty_vectors(dummy_hash=self.vocab.strings[""])
- def initialize_entities(self, int64_t nr_entities):
+ def _initialize_entities(self, int64_t nr_entities):
self._entry_index = PreshMap(nr_entities + 1)
self._entries = entry_vec(nr_entities + 1)
- def initialize_vectors(self, int64_t nr_entities):
+ def _initialize_vectors(self, int64_t nr_entities):
self._vectors_table = float_matrix(nr_entities + 1)
- def initialize_aliases(self, int64_t nr_aliases):
+ def _initialize_aliases(self, int64_t nr_aliases):
self._alias_index = PreshMap(nr_aliases + 1)
self._aliases_table = alias_vec(nr_aliases + 1)
- @property
- def entity_vector_length(self):
- """RETURNS (uint64): length of the entity vectors"""
- return self.entity_vector_length
-
def __len__(self):
return self.get_size_entities()
@@ -155,8 +92,8 @@ cdef class KnowledgeBase:
raise ValueError(Errors.E140)
nr_entities = len(set(entity_list))
- self.initialize_entities(nr_entities)
- self.initialize_vectors(nr_entities)
+ self._initialize_entities(nr_entities)
+ self._initialize_vectors(nr_entities)
i = 0
cdef KBEntryC entry
@@ -286,7 +223,10 @@ cdef class KnowledgeBase:
alias_entry.probs = probs
self._aliases_table[alias_index] = alias_entry
- def get_alias_candidates(self, str alias) -> Iterator[Candidate]:
+ def get_candidates(self, mention: Span) -> Iterable[Candidate]:
+ return self.get_alias_candidates(mention.text) # type: ignore
+
+ def get_alias_candidates(self, str alias) -> Iterable[Candidate]:
"""
Return candidate entities for an alias. Each candidate defines the entity, the original alias,
and the prior probability of that alias resolving to that entity.
@@ -388,9 +328,9 @@ cdef class KnowledgeBase:
nr_entities = header[0]
nr_aliases = header[1]
entity_vector_length = header[2]
- self.initialize_entities(nr_entities)
- self.initialize_vectors(nr_entities)
- self.initialize_aliases(nr_aliases)
+ self._initialize_entities(nr_entities)
+ self._initialize_vectors(nr_entities)
+ self._initialize_aliases(nr_aliases)
self.entity_vector_length = entity_vector_length
def deserialize_vectors(b):
@@ -512,8 +452,8 @@ cdef class KnowledgeBase:
cdef int64_t entity_vector_length
reader.read_header(&nr_entities, &entity_vector_length)
- self.initialize_entities(nr_entities)
- self.initialize_vectors(nr_entities)
+ self._initialize_entities(nr_entities)
+ self._initialize_vectors(nr_entities)
self.entity_vector_length = entity_vector_length
# STEP 1: load entity vectors
@@ -552,7 +492,7 @@ cdef class KnowledgeBase:
# STEP 3: load aliases
cdef int64_t nr_aliases
reader.read_alias_length(&nr_aliases)
- self.initialize_aliases(nr_aliases)
+ self._initialize_aliases(nr_aliases)
cdef int64_t nr_candidates
cdef vector[int64_t] entry_indices
diff --git a/spacy/lang/bg/__init__.py b/spacy/lang/bg/__init__.py
index 559cc34c4..c9176b946 100644
--- a/spacy/lang/bg/__init__.py
+++ b/spacy/lang/bg/__init__.py
@@ -2,7 +2,8 @@ from .stop_words import STOP_WORDS
from .tokenizer_exceptions import TOKENIZER_EXCEPTIONS
from .lex_attrs import LEX_ATTRS
from ..tokenizer_exceptions import BASE_EXCEPTIONS
-
+from ..punctuation import COMBINING_DIACRITICS_TOKENIZER_INFIXES
+from ..punctuation import COMBINING_DIACRITICS_TOKENIZER_SUFFIXES
from ...language import Language, BaseDefaults
from ...attrs import LANG
from ...util import update_exc
@@ -16,6 +17,8 @@ class BulgarianDefaults(BaseDefaults):
stop_words = STOP_WORDS
tokenizer_exceptions = update_exc(BASE_EXCEPTIONS, TOKENIZER_EXCEPTIONS)
+ suffixes = COMBINING_DIACRITICS_TOKENIZER_SUFFIXES
+ infixes = COMBINING_DIACRITICS_TOKENIZER_INFIXES
class Bulgarian(Language):
diff --git a/spacy/lang/ca/lemmatizer.py b/spacy/lang/ca/lemmatizer.py
index 2fd012912..0f15e6e65 100644
--- a/spacy/lang/ca/lemmatizer.py
+++ b/spacy/lang/ca/lemmatizer.py
@@ -72,10 +72,10 @@ class CatalanLemmatizer(Lemmatizer):
oov_forms.append(form)
if not forms:
forms.extend(oov_forms)
- if not forms and string in lookup_table.keys():
- forms.append(self.lookup_lemmatize(token)[0])
+
+ # use lookups, and fall back to the token itself
if not forms:
- forms.append(string)
+ forms.append(lookup_table.get(string, [string])[0])
forms = list(dict.fromkeys(forms))
self.cache[cache_key] = forms
return forms
diff --git a/spacy/lang/char_classes.py b/spacy/lang/char_classes.py
index b15bb3cf3..37c58c85f 100644
--- a/spacy/lang/char_classes.py
+++ b/spacy/lang/char_classes.py
@@ -258,6 +258,10 @@ ALPHA = group_chars(
ALPHA_LOWER = group_chars(_lower + _uncased)
ALPHA_UPPER = group_chars(_upper + _uncased)
+_combining_diacritics = r"\u0300-\u036f"
+
+COMBINING_DIACRITICS = _combining_diacritics
+
_units = (
"km km² km³ m m² m³ dm dm² dm³ cm cm² cm³ mm mm² mm³ ha µm nm yd in ft "
"kg g mg µg t lb oz m/s km/h kmh mph hPa Pa mbar mb MB kb KB gb GB tb "
@@ -276,7 +280,7 @@ _currency = (
_punct = (
r"… …… , : ; \! \? ¿ ؟ ¡ \( \) \[ \] \{ \} < > _ # \* & 。 ? ! , 、 ; : ~ · । ، ۔ ؛ ٪"
)
-_quotes = r'\' " ” “ ` ‘ ´ ’ ‚ , „ » « 「 」 『 』 ( ) 〔 〕 【 】 《 》 〈 〉'
+_quotes = r'\' " ” “ ` ‘ ´ ’ ‚ , „ » « 「 」 『 』 ( ) 〔 〕 【 】 《 》 〈 〉 〈 〉 ⟦ ⟧'
_hyphens = "- – — -- --- —— ~"
# Various symbols like dingbats, but also emoji
diff --git a/spacy/lang/dsb/__init__.py b/spacy/lang/dsb/__init__.py
new file mode 100644
index 000000000..c66092a0c
--- /dev/null
+++ b/spacy/lang/dsb/__init__.py
@@ -0,0 +1,16 @@
+from .lex_attrs import LEX_ATTRS
+from .stop_words import STOP_WORDS
+from ...language import Language, BaseDefaults
+
+
+class LowerSorbianDefaults(BaseDefaults):
+ lex_attr_getters = LEX_ATTRS
+ stop_words = STOP_WORDS
+
+
+class LowerSorbian(Language):
+ lang = "dsb"
+ Defaults = LowerSorbianDefaults
+
+
+__all__ = ["LowerSorbian"]
diff --git a/spacy/lang/dsb/examples.py b/spacy/lang/dsb/examples.py
new file mode 100644
index 000000000..6e9143826
--- /dev/null
+++ b/spacy/lang/dsb/examples.py
@@ -0,0 +1,15 @@
+"""
+Example sentences to test spaCy and its language models.
+
+>>> from spacy.lang.dsb.examples import sentences
+>>> docs = nlp.pipe(sentences)
+"""
+
+
+sentences = [
+ "Z tym stwori so wuměnjenje a zakład za dalše wobdźěłanje přez analyzu tekstoweje struktury a semantisku anotaciju a z tym tež za tu předstajenu digitalnu online-wersiju.",
+ "Mi so tu jara derje spodoba.",
+ "Kotre nowniny chceće měć?",
+ "Tak ako w slědnem lěśe jo teke lětosa jano doma zapustowaś móžno.",
+ "Zwóstanjo pótakem hyšći wjele źěła.",
+]
diff --git a/spacy/lang/dsb/lex_attrs.py b/spacy/lang/dsb/lex_attrs.py
new file mode 100644
index 000000000..367b3afb8
--- /dev/null
+++ b/spacy/lang/dsb/lex_attrs.py
@@ -0,0 +1,113 @@
+from ...attrs import LIKE_NUM
+
+_num_words = [
+ "nul",
+ "jaden",
+ "jadna",
+ "jadno",
+ "dwa",
+ "dwě",
+ "tśi",
+ "tśo",
+ "styri",
+ "styrjo",
+ "pěś",
+ "pěśo",
+ "šesć",
+ "šesćo",
+ "sedym",
+ "sedymjo",
+ "wósym",
+ "wósymjo",
+ "źewjeś",
+ "źewjeśo",
+ "źaseś",
+ "źaseśo",
+ "jadnassćo",
+ "dwanassćo",
+ "tśinasćo",
+ "styrnasćo",
+ "pěśnasćo",
+ "šesnasćo",
+ "sedymnasćo",
+ "wósymnasćo",
+ "źewjeśnasćo",
+ "dwanasćo",
+ "dwaźasća",
+ "tśiźasća",
+ "styrźasća",
+ "pěśźaset",
+ "šesćźaset",
+ "sedymźaset",
+ "wósymźaset",
+ "źewjeśźaset",
+ "sto",
+ "tysac",
+ "milion",
+ "miliarda",
+ "bilion",
+ "biliarda",
+ "trilion",
+ "triliarda",
+]
+
+_ordinal_words = [
+ "prědny",
+ "prědna",
+ "prědne",
+ "drugi",
+ "druga",
+ "druge",
+ "tśeśi",
+ "tśeśa",
+ "tśeśe",
+ "stwórty",
+ "stwórta",
+ "stwórte",
+ "pêty",
+ "pěta",
+ "pête",
+ "šesty",
+ "šesta",
+ "šeste",
+ "sedymy",
+ "sedyma",
+ "sedyme",
+ "wósymy",
+ "wósyma",
+ "wósyme",
+ "źewjety",
+ "źewjeta",
+ "źewjete",
+ "źasety",
+ "źaseta",
+ "źasete",
+ "jadnasty",
+ "jadnasta",
+ "jadnaste",
+ "dwanasty",
+ "dwanasta",
+ "dwanaste",
+]
+
+
+def like_num(text):
+ if text.startswith(("+", "-", "±", "~")):
+ text = text[1:]
+ text = text.replace(",", "").replace(".", "")
+ if text.isdigit():
+ return True
+ if text.count("/") == 1:
+ num, denom = text.split("/")
+ if num.isdigit() and denom.isdigit():
+ return True
+ text_lower = text.lower()
+ if text_lower in _num_words:
+ return True
+ # Check ordinal number
+ if text_lower in _ordinal_words:
+ return True
+ return False
+
+
+LEX_ATTRS = {LIKE_NUM: like_num}
diff --git a/spacy/lang/dsb/stop_words.py b/spacy/lang/dsb/stop_words.py
new file mode 100644
index 000000000..376e04aa6
--- /dev/null
+++ b/spacy/lang/dsb/stop_words.py
@@ -0,0 +1,15 @@
+STOP_WORDS = set(
+ """
+a abo aby ako ale až
+
+daniž dokulaž
+
+gaž
+
+jolic
+
+pak pótom
+
+teke togodla
+""".split()
+)
diff --git a/spacy/lang/en/tokenizer_exceptions.py b/spacy/lang/en/tokenizer_exceptions.py
index 55b544e42..7886e28cb 100644
--- a/spacy/lang/en/tokenizer_exceptions.py
+++ b/spacy/lang/en/tokenizer_exceptions.py
@@ -35,7 +35,7 @@ for pron in ["i"]:
_exc[orth + "m"] = [
{ORTH: orth, NORM: pron},
- {ORTH: "m", "tenspect": 1, "number": 1},
+ {ORTH: "m"},
]
_exc[orth + "'ma"] = [
@@ -139,26 +139,27 @@ for pron in ["he", "she", "it"]:
# W-words, relative pronouns, prepositions etc.
-for word in [
- "who",
- "what",
- "when",
- "where",
- "why",
- "how",
- "there",
- "that",
- "this",
- "these",
- "those",
+for word, morph in [
+ ("who", None),
+ ("what", None),
+ ("when", None),
+ ("where", None),
+ ("why", None),
+ ("how", None),
+ ("there", None),
+ ("that", "Number=Sing|Person=3"),
+ ("this", "Number=Sing|Person=3"),
+ ("these", "Number=Plur|Person=3"),
+ ("those", "Number=Plur|Person=3"),
]:
for orth in [word, word.title()]:
- _exc[orth + "'s"] = [
- {ORTH: orth, NORM: word},
- {ORTH: "'s", NORM: "'s"},
- ]
+ if morph != "Number=Plur|Person=3":
+ _exc[orth + "'s"] = [
+ {ORTH: orth, NORM: word},
+ {ORTH: "'s", NORM: "'s"},
+ ]
- _exc[orth + "s"] = [{ORTH: orth, NORM: word}, {ORTH: "s"}]
+ _exc[orth + "s"] = [{ORTH: orth, NORM: word}, {ORTH: "s"}]
_exc[orth + "'ll"] = [
{ORTH: orth, NORM: word},
@@ -182,25 +183,26 @@ for word in [
{ORTH: "ve", NORM: "have"},
]
- _exc[orth + "'re"] = [
- {ORTH: orth, NORM: word},
- {ORTH: "'re", NORM: "are"},
- ]
+ if morph != "Number=Sing|Person=3":
+ _exc[orth + "'re"] = [
+ {ORTH: orth, NORM: word},
+ {ORTH: "'re", NORM: "are"},
+ ]
- _exc[orth + "re"] = [
- {ORTH: orth, NORM: word},
- {ORTH: "re", NORM: "are"},
- ]
+ _exc[orth + "re"] = [
+ {ORTH: orth, NORM: word},
+ {ORTH: "re", NORM: "are"},
+ ]
- _exc[orth + "'ve"] = [
- {ORTH: orth, NORM: word},
- {ORTH: "'ve"},
- ]
+ _exc[orth + "'ve"] = [
+ {ORTH: orth, NORM: word},
+ {ORTH: "'ve"},
+ ]
- _exc[orth + "ve"] = [
- {ORTH: orth},
- {ORTH: "ve", NORM: "have"},
- ]
+ _exc[orth + "ve"] = [
+ {ORTH: orth},
+ {ORTH: "ve", NORM: "have"},
+ ]
_exc[orth + "'d"] = [
{ORTH: orth, NORM: word},
@@ -447,7 +449,6 @@ for exc_data in [
{ORTH: "La.", NORM: "Louisiana"},
{ORTH: "Mar.", NORM: "March"},
{ORTH: "Mass.", NORM: "Massachusetts"},
- {ORTH: "May.", NORM: "May"},
{ORTH: "Mich.", NORM: "Michigan"},
{ORTH: "Minn.", NORM: "Minnesota"},
{ORTH: "Miss.", NORM: "Mississippi"},
diff --git a/spacy/lang/es/examples.py b/spacy/lang/es/examples.py
index 2bcbd8740..e4dfbcb6d 100644
--- a/spacy/lang/es/examples.py
+++ b/spacy/lang/es/examples.py
@@ -9,14 +9,14 @@ Example sentences to test spaCy and its language models.
sentences = [
"Apple está buscando comprar una startup del Reino Unido por mil millones de dólares.",
"Los coches autónomos delegan la responsabilidad del seguro en sus fabricantes.",
- "San Francisco analiza prohibir los robots delivery.",
+ "San Francisco analiza prohibir los robots de reparto.",
"Londres es una gran ciudad del Reino Unido.",
"El gato come pescado.",
"Veo al hombre con el telescopio.",
"La araña come moscas.",
"El pingüino incuba en su nido sobre el hielo.",
- "¿Dónde estais?",
- "¿Quién es el presidente Francés?",
- "¿Dónde está encuentra la capital de Argentina?",
+ "¿Dónde estáis?",
+ "¿Quién es el presidente francés?",
+ "¿Dónde se encuentra la capital de Argentina?",
"¿Cuándo nació José de San Martín?",
]
diff --git a/spacy/lang/es/stop_words.py b/spacy/lang/es/stop_words.py
index 004df4fca..6d2885481 100644
--- a/spacy/lang/es/stop_words.py
+++ b/spacy/lang/es/stop_words.py
@@ -1,82 +1,80 @@
STOP_WORDS = set(
"""
-actualmente acuerdo adelante ademas además adrede afirmó agregó ahi ahora ahí
-al algo alguna algunas alguno algunos algún alli allí alrededor ambos ampleamos
-antano antaño ante anterior antes apenas aproximadamente aquel aquella aquellas
-aquello aquellos aqui aquél aquélla aquéllas aquéllos aquí arriba arribaabajo
-aseguró asi así atras aun aunque ayer añadió aún
+a acuerdo adelante ademas además afirmó agregó ahi ahora ahí al algo alguna
+algunas alguno algunos algún alli allí alrededor ambos ante anterior antes
+apenas aproximadamente aquel aquella aquellas aquello aquellos aqui aquél
+aquélla aquéllas aquéllos aquí arriba aseguró asi así atras aun aunque añadió
+aún
bajo bastante bien breve buen buena buenas bueno buenos
-cada casi cerca cierta ciertas cierto ciertos cinco claro comentó como con
-conmigo conocer conseguimos conseguir considera consideró consigo consigue
-consiguen consigues contigo contra cosas creo cual cuales cualquier cuando
-cuanta cuantas cuanto cuantos cuatro cuenta cuál cuáles cuándo cuánta cuántas
-cuánto cuántos cómo
+cada casi cierta ciertas cierto ciertos cinco claro comentó como con conmigo
+conocer conseguimos conseguir considera consideró consigo consigue consiguen
+consigues contigo contra creo cual cuales cualquier cuando cuanta cuantas
+cuanto cuantos cuatro cuenta cuál cuáles cuándo cuánta cuántas cuánto cuántos
+cómo
da dado dan dar de debajo debe deben debido decir dejó del delante demasiado
demás dentro deprisa desde despacio despues después detras detrás dia dias dice
-dicen dicho dieron diferente diferentes dijeron dijo dio donde dos durante día
-días dónde
+dicen dicho dieron diez diferente diferentes dijeron dijo dio doce donde dos
+durante día días dónde
-ejemplo el ella ellas ello ellos embargo empleais emplean emplear empleas
-empleo en encima encuentra enfrente enseguida entonces entre era eramos eran
-eras eres es esa esas ese eso esos esta estaba estaban estado estados estais
-estamos estan estar estará estas este esto estos estoy estuvo está están ex
-excepto existe existen explicó expresó él ésa ésas ése ésos ésta éstas éste
-éstos
+e el ella ellas ello ellos embargo en encima encuentra enfrente enseguida
+entonces entre era eramos eran eras eres es esa esas ese eso esos esta estaba
+estaban estado estados estais estamos estan estar estará estas este esto estos
+estoy estuvo está están excepto existe existen explicó expresó él ésa ésas ése
+ésos ésta éstas éste éstos
fin final fue fuera fueron fui fuimos
-general gran grandes gueno
+gran grande grandes
ha haber habia habla hablan habrá había habían hace haceis hacemos hacen hacer
hacerlo haces hacia haciendo hago han hasta hay haya he hecho hemos hicieron
-hizo horas hoy hubo
+hizo hoy hubo
-igual incluso indicó informo informó intenta intentais intentamos intentan
-intentar intentas intento ir
+igual incluso indicó informo informó ir
junto
-la lado largo las le lejos les llegó lleva llevar lo los luego lugar
+la lado largo las le les llegó lleva llevar lo los luego
mal manera manifestó mas mayor me mediante medio mejor mencionó menos menudo mi
-mia mias mientras mio mios mis misma mismas mismo mismos modo momento mucha
-muchas mucho muchos muy más mí mía mías mío míos
+mia mias mientras mio mios mis misma mismas mismo mismos modo mucha muchas
+mucho muchos muy más mí mía mías mío míos
nada nadie ni ninguna ningunas ninguno ningunos ningún no nos nosotras nosotros
-nuestra nuestras nuestro nuestros nueva nuevas nuevo nuevos nunca
+nuestra nuestras nuestro nuestros nueva nuevas nueve nuevo nuevos nunca
-ocho os otra otras otro otros
+o ocho once os otra otras otro otros
-pais para parece parte partir pasada pasado paìs peor pero pesar poca pocas
-poco pocos podeis podemos poder podria podriais podriamos podrian podrias podrá
+para parece parte partir pasada pasado paìs peor pero pesar poca pocas poco
+pocos podeis podemos poder podria podriais podriamos podrian podrias podrá
podrán podría podrían poner por porque posible primer primera primero primeros
-principalmente pronto propia propias propio propios proximo próximo próximos
-pudo pueda puede pueden puedo pues
+pronto propia propias propio propios proximo próximo próximos pudo pueda puede
+pueden puedo pues
-qeu que quedó queremos quien quienes quiere quiza quizas quizá quizás quién quiénes qué
+qeu que quedó queremos quien quienes quiere quiza quizas quizá quizás quién
+quiénes qué
-raras realizado realizar realizó repente respecto
+realizado realizar realizó repente respecto
sabe sabeis sabemos saben saber sabes salvo se sea sean segun segunda segundo
según seis ser sera será serán sería señaló si sido siempre siendo siete sigue
-siguiente sin sino sobre sois sola solamente solas solo solos somos son soy
-soyos su supuesto sus suya suyas suyo sé sí sólo
+siguiente sin sino sobre sois sola solamente solas solo solos somos son soy su
+supuesto sus suya suyas suyo suyos sé sí sólo
tal tambien también tampoco tan tanto tarde te temprano tendrá tendrán teneis
-tenemos tener tenga tengo tenido tenía tercera ti tiempo tiene tienen toda
-todas todavia todavía todo todos total trabaja trabajais trabajamos trabajan
-trabajar trabajas trabajo tras trata través tres tu tus tuvo tuya tuyas tuyo
-tuyos tú
+tenemos tener tenga tengo tenido tenía tercera tercero ti tiene tienen toda
+todas todavia todavía todo todos total tras trata través tres tu tus tuvo tuya
+tuyas tuyo tuyos tú
-ultimo un una unas uno unos usa usais usamos usan usar usas uso usted ustedes
+u ultimo un una unas uno unos usa usais usamos usan usar usas uso usted ustedes
última últimas último últimos
-va vais valor vamos van varias varios vaya veces ver verdad verdadera verdadero
-vez vosotras vosotros voy vuestra vuestras vuestro vuestros
+va vais vamos van varias varios vaya veces ver verdad verdadera verdadero vez
+vosotras vosotros voy vuestra vuestras vuestro vuestros
-ya yo
+y ya yo
""".split()
)
diff --git a/spacy/lang/fr/lemmatizer.py b/spacy/lang/fr/lemmatizer.py
index c6422cf96..a7cbe0bcf 100644
--- a/spacy/lang/fr/lemmatizer.py
+++ b/spacy/lang/fr/lemmatizer.py
@@ -53,11 +53,16 @@ class FrenchLemmatizer(Lemmatizer):
rules = rules_table.get(univ_pos, [])
string = string.lower()
forms = []
+ # first try lookup in table based on upos
if string in index:
forms.append(string)
self.cache[cache_key] = forms
return forms
+
+ # then add anything in the exceptions table
forms.extend(exceptions.get(string, []))
+
+ # if nothing found yet, use the rules
oov_forms = []
if not forms:
for old, new in rules:
@@ -69,12 +74,14 @@ class FrenchLemmatizer(Lemmatizer):
forms.append(form)
else:
oov_forms.append(form)
+
+ # if still nothing, add the oov forms from rules
if not forms:
forms.extend(oov_forms)
- if not forms and string in lookup_table.keys():
- forms.append(self.lookup_lemmatize(token)[0])
+
+ # use lookups, which fall back to the token itself
if not forms:
- forms.append(string)
+ forms.append(lookup_table.get(string, [string])[0])
forms = list(dict.fromkeys(forms))
self.cache[cache_key] = forms
return forms
diff --git a/spacy/lang/fr/lex_attrs.py b/spacy/lang/fr/lex_attrs.py
index da98c6e37..811312ad7 100644
--- a/spacy/lang/fr/lex_attrs.py
+++ b/spacy/lang/fr/lex_attrs.py
@@ -3,7 +3,7 @@ from ...attrs import LIKE_NUM
_num_words = set(
"""
-zero un deux trois quatre cinq six sept huit neuf dix
+zero un une deux trois quatre cinq six sept huit neuf dix
onze douze treize quatorze quinze seize dix-sept dix-huit dix-neuf
vingt trente quarante cinquante soixante soixante-dix septante quatre-vingt huitante quatre-vingt-dix nonante
cent mille mil million milliard billion quadrillion quintillion
@@ -13,7 +13,7 @@ sextillion septillion octillion nonillion decillion
_ordinal_words = set(
"""
-premier deuxième second troisième quatrième cinquième sixième septième huitième neuvième dixième
+premier première deuxième second seconde troisième quatrième cinquième sixième septième huitième neuvième dixième
onzième douzième treizième quatorzième quinzième seizième dix-septième dix-huitième dix-neuvième
vingtième trentième quarantième cinquantième soixantième soixante-dixième septantième quatre-vingtième huitantième quatre-vingt-dixième nonantième
centième millième millionnième milliardième billionnième quadrillionnième quintillionnième
diff --git a/spacy/lang/grc/__init__.py b/spacy/lang/grc/__init__.py
index e83f0c5a5..019b3802e 100644
--- a/spacy/lang/grc/__init__.py
+++ b/spacy/lang/grc/__init__.py
@@ -1,11 +1,15 @@
from .tokenizer_exceptions import TOKENIZER_EXCEPTIONS
from .stop_words import STOP_WORDS
from .lex_attrs import LEX_ATTRS
+from .punctuation import TOKENIZER_PREFIXES, TOKENIZER_SUFFIXES, TOKENIZER_INFIXES
from ...language import Language, BaseDefaults
class AncientGreekDefaults(BaseDefaults):
tokenizer_exceptions = TOKENIZER_EXCEPTIONS
+ prefixes = TOKENIZER_PREFIXES
+ suffixes = TOKENIZER_SUFFIXES
+ infixes = TOKENIZER_INFIXES
lex_attr_getters = LEX_ATTRS
stop_words = STOP_WORDS
diff --git a/spacy/lang/grc/punctuation.py b/spacy/lang/grc/punctuation.py
new file mode 100644
index 000000000..8f3589e9a
--- /dev/null
+++ b/spacy/lang/grc/punctuation.py
@@ -0,0 +1,46 @@
+from ..char_classes import LIST_PUNCT, LIST_ELLIPSES, LIST_QUOTES, LIST_CURRENCY
+from ..char_classes import LIST_ICONS, ALPHA_LOWER, ALPHA_UPPER, ALPHA, HYPHENS
+from ..char_classes import CONCAT_QUOTES
+
+_prefixes = (
+ [
+ "†",
+ "⸏",
+ ]
+ + LIST_PUNCT
+ + LIST_ELLIPSES
+ + LIST_QUOTES
+ + LIST_CURRENCY
+ + LIST_ICONS
+)
+
+_suffixes = (
+ LIST_PUNCT
+ + LIST_ELLIPSES
+ + LIST_QUOTES
+ + LIST_ICONS
+ + [
+ "†",
+ "⸎",
+ r"(?<=[\u1F00-\u1FFF\u0370-\u03FF])[\-\.⸏]",
+ ]
+)
+
+_infixes = (
+ LIST_ELLIPSES
+ + LIST_ICONS
+ + [
+ r"(?<=[0-9])[+\-\*^](?=[0-9-])",
+ r"(?<=[{al}{q}])\.(?=[{au}{q}])".format(
+ al=ALPHA_LOWER, au=ALPHA_UPPER, q=CONCAT_QUOTES
+ ),
+ r"(?<=[{a}]),(?=[{a}])".format(a=ALPHA),
+ r"(?<=[{a}0-9])(?:{h})(?=[{a}])".format(a=ALPHA, h=HYPHENS),
+ r"(?<=[{a}0-9])[:<>=/](?=[{a}])".format(a=ALPHA),
+ r"(?<=[\u1F00-\u1FFF\u0370-\u03FF])—",
+ ]
+)
+
+TOKENIZER_PREFIXES = _prefixes
+TOKENIZER_SUFFIXES = _suffixes
+TOKENIZER_INFIXES = _infixes
diff --git a/spacy/lang/hsb/__init__.py b/spacy/lang/hsb/__init__.py
new file mode 100644
index 000000000..034d82319
--- /dev/null
+++ b/spacy/lang/hsb/__init__.py
@@ -0,0 +1,18 @@
+from .lex_attrs import LEX_ATTRS
+from .stop_words import STOP_WORDS
+from .tokenizer_exceptions import TOKENIZER_EXCEPTIONS
+from ...language import Language, BaseDefaults
+
+
+class UpperSorbianDefaults(BaseDefaults):
+ lex_attr_getters = LEX_ATTRS
+ stop_words = STOP_WORDS
+ tokenizer_exceptions = TOKENIZER_EXCEPTIONS
+
+
+class UpperSorbian(Language):
+ lang = "hsb"
+ Defaults = UpperSorbianDefaults
+
+
+__all__ = ["UpperSorbian"]
diff --git a/spacy/lang/hsb/examples.py b/spacy/lang/hsb/examples.py
new file mode 100644
index 000000000..21f6f7584
--- /dev/null
+++ b/spacy/lang/hsb/examples.py
@@ -0,0 +1,15 @@
+"""
+Example sentences to test spaCy and its language models.
+
+>>> from spacy.lang.hsb.examples import sentences
+>>> docs = nlp.pipe(sentences)
+"""
+
+
+sentences = [
+ "To běšo wjelgin raźone a jo se wót luźi derje pśiwzeło. Tak som dožywiła wjelgin",
+ "Jogo pśewóźowarce stej groniłej, až how w serbskich stronach njama Santa Claus nic pytaś.",
+ "A ten sobuźěłaśeŕ Statneje biblioteki w Barlinju jo pśimjeł drogotne knigły bźez rukajcowu z nagima rukoma!",
+ "Take wobchadanje z našym kulturnym derbstwom zewšym njejźo.",
+ "Wopśimjeśe drugich pśinoskow jo było na wusokem niwowje, ako pśecej.",
+]
diff --git a/spacy/lang/hsb/lex_attrs.py b/spacy/lang/hsb/lex_attrs.py
new file mode 100644
index 000000000..5f300a73d
--- /dev/null
+++ b/spacy/lang/hsb/lex_attrs.py
@@ -0,0 +1,106 @@
+from ...attrs import LIKE_NUM
+
+_num_words = [
+ "nul",
+ "jedyn",
+ "jedna",
+ "jedne",
+ "dwaj",
+ "dwě",
+ "tři",
+ "třo",
+ "štyri",
+ "štyrjo",
+ "pjeć",
+ "šěsć",
+ "sydom",
+ "wosom",
+ "dźewjeć",
+ "dźesać",
+ "jědnaće",
+ "dwanaće",
+ "třinaće",
+ "štyrnaće",
+ "pjatnaće",
+ "šěsnaće",
+ "sydomnaće",
+ "wosomnaće",
+ "dźewjatnaće",
+ "dwaceći",
+ "třiceći",
+ "štyrceći",
+ "pjećdźesat",
+ "šěsćdźesat",
+ "sydomdźesat",
+ "wosomdźesat",
+ "dźewjećdźesat",
+ "sto",
+ "tysac",
+ "milion",
+ "miliarda",
+ "bilion",
+ "biliarda",
+ "trilion",
+ "triliarda",
+]
+
+_ordinal_words = [
+ "prěni",
+ "prěnja",
+ "prěnje",
+ "druhi",
+ "druha",
+ "druhe",
+ "třeći",
+ "třeća",
+ "třeće",
+ "štwórty",
+ "štwórta",
+ "štwórte",
+ "pjaty",
+ "pjata",
+ "pjate",
+ "šěsty",
+ "šěsta",
+ "šěste",
+ "sydmy",
+ "sydma",
+ "sydme",
+ "wosmy",
+ "wosma",
+ "wosme",
+ "dźewjaty",
+ "dźewjata",
+ "dźewjate",
+ "dźesaty",
+ "dźesata",
+ "dźesate",
+ "jědnaty",
+ "jědnata",
+ "jědnate",
+ "dwanaty",
+ "dwanata",
+ "dwanate",
+]
+
+
+def like_num(text):
+ if text.startswith(("+", "-", "±", "~")):
+ text = text[1:]
+ text = text.replace(",", "").replace(".", "")
+ if text.isdigit():
+ return True
+ if text.count("/") == 1:
+ num, denom = text.split("/")
+ if num.isdigit() and denom.isdigit():
+ return True
+ text_lower = text.lower()
+ if text_lower in _num_words:
+ return True
+ # Check ordinal number
+ if text_lower in _ordinal_words:
+ return True
+ return False
+
+
+LEX_ATTRS = {LIKE_NUM: like_num}
diff --git a/spacy/lang/hsb/stop_words.py b/spacy/lang/hsb/stop_words.py
new file mode 100644
index 000000000..e6fedaf4c
--- /dev/null
+++ b/spacy/lang/hsb/stop_words.py
@@ -0,0 +1,19 @@
+STOP_WORDS = set(
+ """
+a abo ale ani
+
+dokelž
+
+hdyž
+
+jeli jelizo
+
+kaž
+
+pak potom
+
+tež tohodla
+
+zo zoby
+""".split()
+)
diff --git a/spacy/lang/hsb/tokenizer_exceptions.py b/spacy/lang/hsb/tokenizer_exceptions.py
new file mode 100644
index 000000000..4b9a4f98a
--- /dev/null
+++ b/spacy/lang/hsb/tokenizer_exceptions.py
@@ -0,0 +1,18 @@
+from ..tokenizer_exceptions import BASE_EXCEPTIONS
+from ...symbols import ORTH, NORM
+from ...util import update_exc
+
+_exc = dict()
+for exc_data in [
+ {ORTH: "mil.", NORM: "milion"},
+ {ORTH: "wob.", NORM: "wobydler"},
+]:
+ _exc[exc_data[ORTH]] = [exc_data]
+
+for orth in [
+ "resp.",
+]:
+ _exc[orth] = [{ORTH: orth}]
+
+
+TOKENIZER_EXCEPTIONS = update_exc(BASE_EXCEPTIONS, _exc)
diff --git a/spacy/lang/ko/__init__.py b/spacy/lang/ko/__init__.py
index 63bc06665..0e02e4a2d 100644
--- a/spacy/lang/ko/__init__.py
+++ b/spacy/lang/ko/__init__.py
@@ -7,7 +7,7 @@ from .lex_attrs import LEX_ATTRS
from ...language import Language, BaseDefaults
from ...tokens import Doc
from ...scorer import Scorer
-from ...symbols import POS
+from ...symbols import POS, X
from ...training import validate_examples
from ...util import DummyTokenizer, registry, load_config_from_str
from ...vocab import Vocab
@@ -57,7 +57,10 @@ class KoreanTokenizer(DummyTokenizer):
for token, dtoken in zip(doc, dtokens):
first_tag, sep, eomi_tags = dtoken["tag"].partition("+")
token.tag_ = first_tag # stem(어간) or pre-final(선어말 어미)
- token.pos = TAG_MAP[token.tag_][POS]
+ if token.tag_ in TAG_MAP:
+ token.pos = TAG_MAP[token.tag_][POS]
+ else:
+ token.pos = X
token.lemma_ = dtoken["lemma"]
doc.user_data["full_tags"] = [dt["tag"] for dt in dtokens]
return doc
diff --git a/spacy/lang/ko/punctuation.py b/spacy/lang/ko/punctuation.py
index 7f7b40c5b..f5f1c51da 100644
--- a/spacy/lang/ko/punctuation.py
+++ b/spacy/lang/ko/punctuation.py
@@ -3,7 +3,7 @@ from ..punctuation import TOKENIZER_INFIXES as BASE_TOKENIZER_INFIXES
_infixes = (
- ["·", "ㆍ", "\(", "\)"]
+ ["·", "ㆍ", r"\(", r"\)"]
+ [r"(?<=[0-9])~(?=[0-9-])"]
+ LIST_QUOTES
+ BASE_TOKENIZER_INFIXES
diff --git a/spacy/lang/la/__init__.py b/spacy/lang/la/__init__.py
new file mode 100644
index 000000000..15b87c5b9
--- /dev/null
+++ b/spacy/lang/la/__init__.py
@@ -0,0 +1,18 @@
+from ...language import Language, BaseDefaults
+from .tokenizer_exceptions import TOKENIZER_EXCEPTIONS
+from .stop_words import STOP_WORDS
+from .lex_attrs import LEX_ATTRS
+
+
+class LatinDefaults(BaseDefaults):
+ tokenizer_exceptions = TOKENIZER_EXCEPTIONS
+ stop_words = STOP_WORDS
+ lex_attr_getters = LEX_ATTRS
+
+
+class Latin(Language):
+ lang = "la"
+ Defaults = LatinDefaults
+
+
+__all__ = ["Latin"]
diff --git a/spacy/lang/la/lex_attrs.py b/spacy/lang/la/lex_attrs.py
new file mode 100644
index 000000000..9efb4dd3c
--- /dev/null
+++ b/spacy/lang/la/lex_attrs.py
@@ -0,0 +1,34 @@
+from ...attrs import LIKE_NUM
+import re
+
+# cf. Goyvaerts/Levithan 2009; case-insensitive, allow 4
+roman_numerals_compile = re.compile(
+ r"(?i)^(?=[MDCLXVI])M*(C[MD]|D?C{0,4})(X[CL]|L?X{0,4})(I[XV]|V?I{0,4})$"
+)
+
+_num_words = set(
+ """
+unus una unum duo duae tres tria quattuor quinque sex septem octo novem decem
+""".split()
+)
+
+_ordinal_words = set(
+ """
+primus prima primum secundus secunda secundum tertius tertia tertium
+""".split()
+)
+
+
+def like_num(text):
+ if text.isdigit():
+ return True
+ if roman_numerals_compile.match(text):
+ return True
+ if text.lower() in _num_words:
+ return True
+ if text.lower() in _ordinal_words:
+ return True
+ return False
+
+
+LEX_ATTRS = {LIKE_NUM: like_num}
diff --git a/spacy/lang/la/stop_words.py b/spacy/lang/la/stop_words.py
new file mode 100644
index 000000000..8b590bb67
--- /dev/null
+++ b/spacy/lang/la/stop_words.py
@@ -0,0 +1,37 @@
+# Corrected Perseus list, cf. https://wiki.digitalclassicist.org/Stopwords_for_Greek_and_Latin
+
+STOP_WORDS = set(
+ """
+ab ac ad adhuc aliqui aliquis an ante apud at atque aut autem
+
+cum cur
+
+de deinde dum
+
+ego enim ergo es est et etiam etsi ex
+
+fio
+
+haud hic
+
+iam idem igitur ille in infra inter interim ipse is ita
+
+magis modo mox
+
+nam ne nec necque neque nisi non nos
+
+o ob
+
+per possum post pro
+
+quae quam quare qui quia quicumque quidem quilibet quis quisnam quisquam quisque quisquis quo quoniam
+
+sed si sic sive sub sui sum super suus
+
+tam tamen trans tu tum
+
+ubi uel uero
+
+vel vero
+""".split()
+)
diff --git a/spacy/lang/la/tokenizer_exceptions.py b/spacy/lang/la/tokenizer_exceptions.py
new file mode 100644
index 000000000..060f6e085
--- /dev/null
+++ b/spacy/lang/la/tokenizer_exceptions.py
@@ -0,0 +1,76 @@
+from ..tokenizer_exceptions import BASE_EXCEPTIONS
+from ...symbols import ORTH
+from ...util import update_exc
+
+
+## TODO: Look into systematically handling u/v
+_exc = {
+ "mecum": [{ORTH: "me"}, {ORTH: "cum"}],
+ "tecum": [{ORTH: "te"}, {ORTH: "cum"}],
+ "nobiscum": [{ORTH: "nobis"}, {ORTH: "cum"}],
+ "vobiscum": [{ORTH: "vobis"}, {ORTH: "cum"}],
+ "uobiscum": [{ORTH: "uobis"}, {ORTH: "cum"}],
+}
+
+for orth in [
+ "A.",
+ "Agr.",
+ "Ap.",
+ "C.",
+ "Cn.",
+ "D.",
+ "F.",
+ "K.",
+ "L.",
+ "M'.",
+ "M.",
+ "Mam.",
+ "N.",
+ "Oct.",
+ "Opet.",
+ "P.",
+ "Paul.",
+ "Post.",
+ "Pro.",
+ "Q.",
+ "S.",
+ "Ser.",
+ "Sert.",
+ "Sex.",
+ "St.",
+ "Sta.",
+ "T.",
+ "Ti.",
+ "V.",
+ "Vol.",
+ "Vop.",
+ "U.",
+ "Uol.",
+ "Uop.",
+ "Ian.",
+ "Febr.",
+ "Mart.",
+ "Apr.",
+ "Mai.",
+ "Iun.",
+ "Iul.",
+ "Aug.",
+ "Sept.",
+ "Oct.",
+ "Nov.",
+ "Nou.",
+ "Dec.",
+ "Non.",
+ "Id.",
+ "A.D.",
+ "Coll.",
+ "Cos.",
+ "Ord.",
+ "Pl.",
+ "S.C.",
+ "Suff.",
+ "Trib.",
+]:
+ _exc[orth] = [{ORTH: orth}]
+
+TOKENIZER_EXCEPTIONS = update_exc(BASE_EXCEPTIONS, _exc)
diff --git a/spacy/lang/lg/__init__.py b/spacy/lang/lg/__init__.py
new file mode 100644
index 000000000..6f7153fce
--- /dev/null
+++ b/spacy/lang/lg/__init__.py
@@ -0,0 +1,18 @@
+from .stop_words import STOP_WORDS
+from .lex_attrs import LEX_ATTRS
+from .punctuation import TOKENIZER_INFIXES
+from ...language import Language, BaseDefaults
+
+
+class LugandaDefaults(BaseDefaults):
+ lex_attr_getters = LEX_ATTRS
+ infixes = TOKENIZER_INFIXES
+ stop_words = STOP_WORDS
+
+
+class Luganda(Language):
+ lang = "lg"
+ Defaults = LugandaDefaults
+
+
+__all__ = ["Luganda"]
diff --git a/spacy/lang/lg/examples.py b/spacy/lang/lg/examples.py
new file mode 100644
index 000000000..5450c5520
--- /dev/null
+++ b/spacy/lang/lg/examples.py
@@ -0,0 +1,17 @@
+"""
+Example sentences to test spaCy and its language models.
+
+>>> from spacy.lang.lg.examples import sentences
+>>> docs = nlp.pipe(sentences)
+"""
+
+sentences = [
+ "Mpa ebyafaayo ku byalo Nakatu ne Nkajja",
+ "Okuyita Ttembo kitegeeza kugwa ddalu",
+ "Ekifumu kino kyali kya mulimu ki?",
+ "Ekkovu we liyise wayitibwa mukululo",
+ "Akola mulimu ki oguvaamu ssente?",
+ "Emisumaali egikomerera embaawo giyitibwa nninga",
+ "Abooluganda ab’emmamba ababiri",
+ "Ekisaawe ky'ebyenjigiriza kya mugaso nnyo",
+]
diff --git a/spacy/lang/lg/lex_attrs.py b/spacy/lang/lg/lex_attrs.py
new file mode 100644
index 000000000..3c60e3d0e
--- /dev/null
+++ b/spacy/lang/lg/lex_attrs.py
@@ -0,0 +1,95 @@
+from ...attrs import LIKE_NUM
+
+_num_words = [
+ "nnooti", # Zero
+ "zeero", # zero
+ "emu", # one
+ "bbiri", # two
+ "ssatu", # three
+ "nnya", # four
+ "ttaano", # five
+ "mukaaga", # six
+ "musanvu", # seven
+ "munaana", # eight
+ "mwenda", # nine
+ "kkumi", # ten
+ "kkumi n'emu", # eleven
+ "kkumi na bbiri", # twelve
+ "kkumi na ssatu", # thirteen
+ "kkumi na nnya", # forteen
+ "kkumi na ttaano", # fifteen
+ "kkumi na mukaaga", # sixteen
+ "kkumi na musanvu", # seventeen
+ "kkumi na munaana", # eighteen
+ "kkumi na mwenda", # nineteen
+ "amakumi abiri", # twenty
+ "amakumi asatu", # thirty
+ "amakumi ana", # forty
+ "amakumi ataano", # fifty
+ "nkaaga", # sixty
+ "nsanvu", # seventy
+ "kinaana", # eighty
+ "kyenda", # ninety
+ "kikumi", # hundred
+ "lukumi", # thousand
+ "kakadde", # million
+ "kawumbi", # billion
+ "kase", # trillion
+ "katabalika", # quadrillion
+ "keesedde", # gajillion
+ "kafukunya", # bazillion
+ "ekisooka", # first
+ "ekyokubiri", # second
+ "ekyokusatu", # third
+ "ekyokuna", # fourth
+ "ekyokutaano", # fifith
+ "ekyomukaaga", # sixth
+ "ekyomusanvu", # seventh
+ "eky'omunaana", # eighth
+ "ekyomwenda", # nineth
+ "ekyekkumi", # tenth
+ "ekyekkumi n'ekimu", # eleventh
+ "ekyekkumi n'ebibiri", # twelveth
+ "ekyekkumi n'ebisatu", # thirteenth
+ "ekyekkumi n'ebina", # fourteenth
+ "ekyekkumi n'ebitaano", # fifteenth
+ "ekyekkumi n'omukaaga", # sixteenth
+ "ekyekkumi n'omusanvu", # seventeenth
+ "ekyekkumi n'omunaana", # eigteenth
+ "ekyekkumi n'omwenda", # nineteenth
+ "ekyamakumi abiri", # twentieth
+ "ekyamakumi asatu", # thirtieth
+ "ekyamakumi ana", # fortieth
+ "ekyamakumi ataano", # fiftieth
+ "ekyenkaaga", # sixtieth
+ "ekyensanvu", # seventieth
+ "ekyekinaana", # eightieth
+ "ekyekyenda", # ninetieth
+ "ekyekikumi", # hundredth
+ "ekyolukumi", # thousandth
+ "ekyakakadde", # millionth
+ "ekyakawumbi", # billionth
+ "ekyakase", # trillionth
+ "ekyakatabalika", # quadrillionth
+ "ekyakeesedde", # gajillionth
+ "ekyakafukunya", # bazillionth
+]
+
+
+def like_num(text):
+ if text.startswith(("+", "-", "±", "~")):
+ text = text[1:]
+ text = text.replace(",", "").replace(".", "")
+ if text.isdigit():
+ return True
+ if text.count("/") == 1:
+ num, denom = text.split("/")
+ if num.isdigit() and denom.isdigit():
+ return True
+ text_lower = text.lower()
+ if text_lower in _num_words:
+ return True
+ return False
+
+
+LEX_ATTRS = {LIKE_NUM: like_num}
diff --git a/spacy/lang/lg/punctuation.py b/spacy/lang/lg/punctuation.py
new file mode 100644
index 000000000..5d3eb792e
--- /dev/null
+++ b/spacy/lang/lg/punctuation.py
@@ -0,0 +1,19 @@
+from ..char_classes import LIST_ELLIPSES, LIST_ICONS, HYPHENS
+from ..char_classes import CONCAT_QUOTES, ALPHA_LOWER, ALPHA_UPPER, ALPHA
+
+_infixes = (
+ LIST_ELLIPSES
+ + LIST_ICONS
+ + [
+ r"(?<=[0-9])[+\-\*^](?=[0-9-])",
+ r"(?<=[{al}{q}])\.(?=[{au}{q}])".format(
+ al=ALPHA_LOWER, au=ALPHA_UPPER, q=CONCAT_QUOTES
+ ),
+ r"(?<=[{a}]),(?=[{a}])".format(a=ALPHA),
+ r"(?<=[{a}0-9])(?:{h})(?=[{a}])".format(a=ALPHA, h=HYPHENS),
+ r"(?<=[{a}0-9])[:<>=/](?=[{a}])".format(a=ALPHA),
+ ]
+)
+
+
+TOKENIZER_INFIXES = _infixes
diff --git a/spacy/lang/lg/stop_words.py b/spacy/lang/lg/stop_words.py
new file mode 100644
index 000000000..7bad59344
--- /dev/null
+++ b/spacy/lang/lg/stop_words.py
@@ -0,0 +1,19 @@
+STOP_WORDS = set(
+ """
+abadde abalala abamu abangi abava ajja ali alina ani anti ateekeddwa atewamu
+atya awamu aweebwa ayinza ba baali babadde babalina bajja
+bajjanewankubade bali balina bandi bangi bano bateekeddwa baweebwa bayina bebombi beera bibye
+bimu bingi bino bo bokka bonna buli bulijjo bulungi bwabwe bwaffe bwayo bwe bwonna bya byabwe
+byaffe byebimu byonna ddaa ddala ddi e ebimu ebiri ebweruobulungi ebyo edda ejja ekirala ekyo
+endala engeri ennyo era erimu erina ffe ffenna ga gujja gumu gunno guno gwa gwe kaseera kati
+kennyini ki kiki kikino kikye kikyo kino kirungi kki ku kubangabyombi kubangaolwokuba kudda
+kuva kuwa kwegamba kyaffe kye kyekimuoyo kyekyo kyonna leero liryo lwa lwaki lyabwezaabwe
+lyaffe lyange mbadde mingi mpozzi mu mulinaoyina munda mwegyabwe nolwekyo nabadde nabo nandiyagadde
+nandiye nanti naye ne nedda neera nga nnyingi nnyini nnyinza nnyo nti nyinza nze oba ojja okudda
+okugenda okuggyako okutuusa okuva okuwa oli olina oluvannyuma olwekyobuva omuli ono osobola otya
+oyina oyo seetaaga si sinakindi singa talina tayina tebaali tebaalina tebayina terina tetulina
+tetuteekeddwa tewali teyalina teyayina tolina tu tuyina tulina tuyina twafuna twetaaga wa wabula
+wabweru wadde waggulunnina wakati waliwobangi waliyo wandi wange wano wansi weebwa yabadde yaffe
+ye yenna yennyini yina yonna ziba zijja zonna
+""".split()
+)
diff --git a/spacy/lang/nl/stop_words.py b/spacy/lang/nl/stop_words.py
index a2c6198e7..cd4fdefdf 100644
--- a/spacy/lang/nl/stop_words.py
+++ b/spacy/lang/nl/stop_words.py
@@ -15,7 +15,7 @@
STOP_WORDS = set(
"""
-aan af al alle alles allebei alleen allen als altijd ander anders andere anderen aangaangde aangezien achter achterna
+aan af al alle alles allebei alleen allen als altijd ander anders andere anderen aangaande aangezien achter achterna
afgelopen aldus alhoewel anderzijds
ben bij bijna bijvoorbeeld behalve beide beiden beneden bent bepaald beter betere betreffende binnen binnenin boven
diff --git a/spacy/lang/nl/syntax_iterators.py b/spacy/lang/nl/syntax_iterators.py
index 1ab5e7cff..be9beabe6 100644
--- a/spacy/lang/nl/syntax_iterators.py
+++ b/spacy/lang/nl/syntax_iterators.py
@@ -40,6 +40,7 @@ def noun_chunks(doclike: Union[Doc, Span]) -> Iterator[Tuple[int, int, int]]:
span_label = doc.vocab.strings.add("NP")
# Only NOUNS and PRONOUNS matter
+ end_span = -1
for i, word in enumerate(filter(lambda x: x.pos in [PRON, NOUN], doclike)):
# For NOUNS
# Pick children from syntactic parse (only those with certain dependencies)
@@ -58,15 +59,17 @@ def noun_chunks(doclike: Union[Doc, Span]) -> Iterator[Tuple[int, int, int]]:
children_i = [c.i for c in children] + [word.i]
start_span = min(children_i)
- end_span = max(children_i) + 1
- yield start_span, end_span, span_label
+ if start_span >= end_span:
+ end_span = max(children_i) + 1
+ yield start_span, end_span, span_label
# PRONOUNS only if it is the subject of a verb
elif word.pos == PRON:
if word.dep in pronoun_deps:
start_span = word.i
- end_span = word.i + 1
- yield start_span, end_span, span_label
+ if start_span >= end_span:
+ end_span = word.i + 1
+ yield start_span, end_span, span_label
SYNTAX_ITERATORS = {"noun_chunks": noun_chunks}
diff --git a/spacy/lang/punctuation.py b/spacy/lang/punctuation.py
index e712e71d6..a1cfe6224 100644
--- a/spacy/lang/punctuation.py
+++ b/spacy/lang/punctuation.py
@@ -1,5 +1,5 @@
from .char_classes import LIST_PUNCT, LIST_ELLIPSES, LIST_QUOTES, LIST_CURRENCY
-from .char_classes import LIST_ICONS, HYPHENS, CURRENCY, UNITS
+from .char_classes import LIST_ICONS, HYPHENS, CURRENCY, UNITS, COMBINING_DIACRITICS
from .char_classes import CONCAT_QUOTES, ALPHA_LOWER, ALPHA_UPPER, ALPHA, PUNCT
@@ -44,3 +44,23 @@ TOKENIZER_INFIXES = (
r"(?<=[{a}0-9])[:<>=/](?=[{a}])".format(a=ALPHA),
]
)
+
+
+# Some languages e.g. written with the Cyrillic alphabet permit the use of diacritics
+# to mark stressed syllables in words where stress is distinctive. Such languages
+# should use the COMBINING_DIACRITICS... suffix and infix regex lists in
+# place of the standard ones.
+COMBINING_DIACRITICS_TOKENIZER_SUFFIXES = list(TOKENIZER_SUFFIXES) + [
+ r"(?<=[{a}][{d}])\.".format(a=ALPHA, d=COMBINING_DIACRITICS),
+]
+
+COMBINING_DIACRITICS_TOKENIZER_INFIXES = list(TOKENIZER_INFIXES) + [
+ r"(?<=[{al}][{d}])\.(?=[{au}{q}])".format(
+ al=ALPHA_LOWER, au=ALPHA_UPPER, q=CONCAT_QUOTES, d=COMBINING_DIACRITICS
+ ),
+ r"(?<=[{a}][{d}]),(?=[{a}])".format(a=ALPHA, d=COMBINING_DIACRITICS),
+ r"(?<=[{a}][{d}])(?:{h})(?=[{a}])".format(
+ a=ALPHA, d=COMBINING_DIACRITICS, h=HYPHENS
+ ),
+ r"(?<=[{a}][{d}])[:<>=/](?=[{a}])".format(a=ALPHA, d=COMBINING_DIACRITICS),
+]
diff --git a/spacy/lang/ru/__init__.py b/spacy/lang/ru/__init__.py
index 5d31d8ea2..7d17628c4 100644
--- a/spacy/lang/ru/__init__.py
+++ b/spacy/lang/ru/__init__.py
@@ -5,6 +5,8 @@ from .stop_words import STOP_WORDS
from .tokenizer_exceptions import TOKENIZER_EXCEPTIONS
from .lex_attrs import LEX_ATTRS
from .lemmatizer import RussianLemmatizer
+from ..punctuation import COMBINING_DIACRITICS_TOKENIZER_INFIXES
+from ..punctuation import COMBINING_DIACRITICS_TOKENIZER_SUFFIXES
from ...language import Language, BaseDefaults
@@ -12,6 +14,8 @@ class RussianDefaults(BaseDefaults):
tokenizer_exceptions = TOKENIZER_EXCEPTIONS
lex_attr_getters = LEX_ATTRS
stop_words = STOP_WORDS
+ suffixes = COMBINING_DIACRITICS_TOKENIZER_SUFFIXES
+ infixes = COMBINING_DIACRITICS_TOKENIZER_INFIXES
class Russian(Language):
@@ -24,7 +28,7 @@ class Russian(Language):
assigns=["token.lemma"],
default_config={
"model": None,
- "mode": "pymorphy2",
+ "mode": "pymorphy3",
"overwrite": False,
"scorer": {"@scorers": "spacy.lemmatizer_scorer.v1"},
},
diff --git a/spacy/lang/ru/lemmatizer.py b/spacy/lang/ru/lemmatizer.py
index 85180b1e4..f4a35de38 100644
--- a/spacy/lang/ru/lemmatizer.py
+++ b/spacy/lang/ru/lemmatizer.py
@@ -19,33 +19,48 @@ class RussianLemmatizer(Lemmatizer):
model: Optional[Model],
name: str = "lemmatizer",
*,
- mode: str = "pymorphy2",
+ mode: str = "pymorphy3",
overwrite: bool = False,
scorer: Optional[Callable] = lemmatizer_score,
) -> None:
- if mode == "pymorphy2":
+ if mode in {"pymorphy2", "pymorphy2_lookup"}:
try:
from pymorphy2 import MorphAnalyzer
except ImportError:
raise ImportError(
- "The Russian lemmatizer mode 'pymorphy2' requires the "
- "pymorphy2 library. Install it with: pip install pymorphy2"
+ "The lemmatizer mode 'pymorphy2' requires the "
+ "pymorphy2 library and dictionaries. Install them with: "
+ "pip install pymorphy2"
+ "# for Ukrainian dictionaries:"
+ "pip install pymorphy2-dicts-uk"
) from None
if getattr(self, "_morph", None) is None:
- self._morph = MorphAnalyzer()
+ self._morph = MorphAnalyzer(lang="ru")
+ elif mode in {"pymorphy3", "pymorphy3_lookup"}:
+ try:
+ from pymorphy3 import MorphAnalyzer
+ except ImportError:
+ raise ImportError(
+ "The lemmatizer mode 'pymorphy3' requires the "
+ "pymorphy3 library and dictionaries. Install them with: "
+ "pip install pymorphy3"
+ "# for Ukrainian dictionaries:"
+ "pip install pymorphy3-dicts-uk"
+ ) from None
+ if getattr(self, "_morph", None) is None:
+ self._morph = MorphAnalyzer(lang="ru")
super().__init__(
vocab, model, name, mode=mode, overwrite=overwrite, scorer=scorer
)
- def pymorphy2_lemmatize(self, token: Token) -> List[str]:
+ def _pymorphy_lemmatize(self, token: Token) -> List[str]:
string = token.text
univ_pos = token.pos_
morphology = token.morph.to_dict()
if univ_pos == "PUNCT":
return [PUNCT_RULES.get(string, string)]
if univ_pos not in ("ADJ", "DET", "NOUN", "NUM", "PRON", "PROPN", "VERB"):
- # Skip unchangeable pos
- return [string.lower()]
+ return self._pymorphy_lookup_lemmatize(token)
analyses = self._morph.parse(string)
filtered_analyses = []
for analysis in analyses:
@@ -53,8 +68,10 @@ class RussianLemmatizer(Lemmatizer):
# Skip suggested parse variant for unknown word for pymorphy
continue
analysis_pos, _ = oc2ud(str(analysis.tag))
- if analysis_pos == univ_pos or (
- analysis_pos in ("NOUN", "PROPN") and univ_pos in ("NOUN", "PROPN")
+ if (
+ analysis_pos == univ_pos
+ or (analysis_pos in ("NOUN", "PROPN") and univ_pos in ("NOUN", "PROPN"))
+ or ((analysis_pos == "PRON") and (univ_pos == "DET"))
):
filtered_analyses.append(analysis)
if not len(filtered_analyses):
@@ -97,13 +114,28 @@ class RussianLemmatizer(Lemmatizer):
dict.fromkeys([analysis.normal_form for analysis in filtered_analyses])
)
- def pymorphy2_lookup_lemmatize(self, token: Token) -> List[str]:
+ def _pymorphy_lookup_lemmatize(self, token: Token) -> List[str]:
string = token.text
analyses = self._morph.parse(string)
- if len(analyses) == 1:
- return [analyses[0].normal_form]
+ # often multiple forms would derive from the same normal form
+ # thus check _unique_ normal forms
+ normal_forms = set([an.normal_form for an in analyses])
+ if len(normal_forms) == 1:
+ return [next(iter(normal_forms))]
return [string]
+ def pymorphy2_lemmatize(self, token: Token) -> List[str]:
+ return self._pymorphy_lemmatize(token)
+
+ def pymorphy2_lookup_lemmatize(self, token: Token) -> List[str]:
+ return self._pymorphy_lookup_lemmatize(token)
+
+ def pymorphy3_lemmatize(self, token: Token) -> List[str]:
+ return self._pymorphy_lemmatize(token)
+
+ def pymorphy3_lookup_lemmatize(self, token: Token) -> List[str]:
+ return self._pymorphy_lookup_lemmatize(token)
+
def oc2ud(oc_tag: str) -> Tuple[str, Dict[str, str]]:
gram_map = {
diff --git a/spacy/lang/ru/lex_attrs.py b/spacy/lang/ru/lex_attrs.py
index 90802cb9b..2afe47623 100644
--- a/spacy/lang/ru/lex_attrs.py
+++ b/spacy/lang/ru/lex_attrs.py
@@ -6,68 +6,123 @@ _num_words = list(
"""
ноль ноля нолю нолём ноле нулевой нулевого нулевому нулевым нулевом нулевая нулевую нулевое нулевые нулевых нулевыми
-один первого первому единица одного одному первой первом первый первым одним одном во-первых
+четверть четверти четвертью четвертей четвертям четвертями четвертях
-два второго второму второй втором вторым двойка двумя двум двух во-вторых двое две двоих оба обе обеим обеими
-обеих обоим обоими обоих
+треть трети третью третей третям третями третях
+
+половина половины половине половину половиной половин половинам половинами половинах половиною
+
+один одного одному одним одном
+первой первого первому первом первый первым первых
+во-первых
+единица единицы единице единицу единицей единиц единицам единицами единицах единицею
+
+два двумя двум двух двоих двое две
+второго второму второй втором вторым вторых
+двойка двойки двойке двойку двойкой двоек двойкам двойками двойках двойкою
+во-вторых
+оба обе обеим обеими обеих обоим обоими обоих
полтора полторы полутора
-три третьего третьему третьем третьим третий тройка трешка трёшка трояк трёха треха тремя трем трех трое троих трёх
+три третьего третьему третьем третьим третий тремя трем трех трое троих трёх
+тройка тройки тройке тройку тройкою троек тройкам тройками тройках тройкой
+троечка троечки троечке троечку троечкой троечек троечкам троечками троечках троечкой
+трешка трешки трешке трешку трешкой трешек трешкам трешками трешках трешкою
+трёшка трёшки трёшке трёшку трёшкой трёшек трёшкам трёшками трёшках трёшкою
+трояк трояка трояку трояком трояке трояки трояков троякам трояками трояках
+треха треху трехой
+трёха трёху трёхой
+втроем втроём
четыре четвертого четвертому четвертом четвертый четвертым четверка четырьмя четырем четырех четверо четырёх четверым
четверых
+вчетвером
-пять пятерочка пятерка пятого пятому пятом пятый пятым пятью пяти пятеро пятерых пятерыми
+пять пятого пятому пятом пятый пятым пятью пяти пятеро пятерых пятерыми
+впятером
+пятерочка пятерочки пятерочке пятерочками пятерочкой пятерочку пятерочкой пятерочками
+пятёрочка пятёрочки пятёрочке пятёрочками пятёрочкой пятёрочку пятёрочкой пятёрочками
+пятерка пятерки пятерке пятерками пятеркой пятерку пятерками
+пятёрка пятёрки пятёрке пятёрками пятёркой пятёрку пятёрками
+пятёра пятёры пятёре пятёрами пятёрой пятёру пятёрами
+пятера пятеры пятере пятерами пятерой пятеру пятерами
+пятак пятаки пятаке пятаками пятаком пятаку пятаками
шесть шестерка шестого шестому шестой шестом шестым шестью шести шестеро шестерых
+вшестером
-семь семерка седьмого седьмому седьмой седьмом седьмым семью семи семеро
+семь семерка седьмого седьмому седьмой седьмом седьмым семью семи семеро седьмых
+всемером
восемь восьмерка восьмого восьмому восемью восьмой восьмом восьмым восеми восьмером восьми восьмью
+восьмерых
+ввосьмером
девять девятого девятому девятка девятом девятый девятым девятью девяти девятером вдевятером девятерых
+вдевятером
-десять десятого десятому десятка десятом десятый десятым десятью десяти десятером вдесятером
+десять десятого десятому десятка десятом десятый десятым десятью десяти десятером десятых
+вдесятером
одиннадцать одиннадцатого одиннадцатому одиннадцатом одиннадцатый одиннадцатым одиннадцатью одиннадцати
+одиннадцатых
двенадцать двенадцатого двенадцатому двенадцатом двенадцатый двенадцатым двенадцатью двенадцати
+двенадцатых
тринадцать тринадцатого тринадцатому тринадцатом тринадцатый тринадцатым тринадцатью тринадцати
+тринадцатых
четырнадцать четырнадцатого четырнадцатому четырнадцатом четырнадцатый четырнадцатым четырнадцатью четырнадцати
+четырнадцатых
пятнадцать пятнадцатого пятнадцатому пятнадцатом пятнадцатый пятнадцатым пятнадцатью пятнадцати
+пятнадцатых
+пятнарик пятнарику пятнариком пятнарики
шестнадцать шестнадцатого шестнадцатому шестнадцатом шестнадцатый шестнадцатым шестнадцатью шестнадцати
+шестнадцатых
-семнадцать семнадцатого семнадцатому семнадцатом семнадцатый семнадцатым семнадцатью семнадцати
+семнадцать семнадцатого семнадцатому семнадцатом семнадцатый семнадцатым семнадцатью семнадцати семнадцатых
восемнадцать восемнадцатого восемнадцатому восемнадцатом восемнадцатый восемнадцатым восемнадцатью восемнадцати
+восемнадцатых
девятнадцать девятнадцатого девятнадцатому девятнадцатом девятнадцатый девятнадцатым девятнадцатью девятнадцати
+девятнадцатых
-двадцать двадцатого двадцатому двадцатом двадцатый двадцатым двадцатью двадцати
+двадцать двадцатого двадцатому двадцатом двадцатый двадцатым двадцатью двадцати двадцатых
-тридцать тридцатого тридцатому тридцатом тридцатый тридцатым тридцатью тридцати
+четвертак четвертака четвертаке четвертаку четвертаки четвертаком четвертаками
-тридевять
+тридцать тридцатого тридцатому тридцатом тридцатый тридцатым тридцатью тридцати тридцатых
+тридцадка тридцадку тридцадке тридцадки тридцадкой тридцадкою тридцадками
-сорок сорокового сороковому сороковом сороковым сороковой
+тридевять тридевяти тридевятью
-пятьдесят пятьдесятого пятьдесятому пятьюдесятью пятьдесятом пятьдесятый пятьдесятым пятидесяти полтинник
+сорок сорокового сороковому сороковом сороковым сороковой сороковых
+сорокет сорокета сорокету сорокете сорокеты сорокетом сорокетами сорокетам
+
+пятьдесят пятьдесятого пятьдесятому пятьюдесятью пятьдесятом пятьдесятый пятьдесятым пятидесяти пятьдесятых
+полтинник полтинника полтиннике полтиннику полтинники полтинником полтинниками полтинникам полтинниках
+пятидесятка пятидесятке пятидесятку пятидесятки пятидесяткой пятидесятками пятидесяткам пятидесятках
+полтос полтоса полтосе полтосу полтосы полтосом полтосами полтосам полтосах
шестьдесят шестьдесятого шестьдесятому шестьюдесятью шестьдесятом шестьдесятый шестьдесятым шестидесятые шестидесяти
+шестьдесятых
-семьдесят семьдесятого семьдесятому семьюдесятью семьдесятом семьдесятый семьдесятым семидесяти
+семьдесят семьдесятого семьдесятому семьюдесятью семьдесятом семьдесятый семьдесятым семидесяти семьдесятых
восемьдесят восемьдесятого восемьдесятому восемьюдесятью восемьдесятом восемьдесятый восемьдесятым восемидесяти
-восьмидесяти
+восьмидесяти восьмидесятых
-девяносто девяностого девяностому девяностом девяностый девяностым девяноста
+девяносто девяностого девяностому девяностом девяностый девяностым девяноста девяностых
-сто сотого сотому сотка сотня сотом сотен сотый сотым ста
+сто сотого сотому сотом сотен сотый сотым ста
+стольник стольника стольнику стольнике стольники стольником стольниками
+сотка сотки сотке соткой сотками соткам сотках
+сотня сотни сотне сотней сотнями сотням сотнях
двести двумястами двухсотого двухсотому двухсотом двухсотый двухсотым двумстам двухстах двухсот
@@ -77,6 +132,9 @@ _num_words = list(
четырехсот
пятьсот пятисотого пятисотому пятьюстами пятисотом пятисотый пятисотым пятистам пятистах пятисот
+пятисотка пятисотки пятисотке пятисоткой пятисотками пятисоткам пятисоткою пятисотках
+пятихатка пятихатки пятихатке пятихаткой пятихатками пятихаткам пятихаткою пятихатках
+пятифан пятифаны пятифане пятифаном пятифанами пятифанах
шестьсот шестисотого шестисотому шестьюстами шестисотом шестисотый шестисотым шестистам шестистах шестисот
@@ -87,23 +145,65 @@ _num_words = list(
девятьсот девятисотого девятисотому девятьюстами девятисотом девятисотый девятисотым девятистам девятистах девятисот
тысяча тысячного тысячному тысячном тысячный тысячным тысячам тысячах тысячей тысяч тысячи тыс
+косарь косаря косару косарем косарями косарях косарям косарей
+
+десятитысячный десятитысячного десятитысячному десятитысячным десятитысячном десятитысячная десятитысячной
+десятитысячную десятитысячною десятитысячное десятитысячные десятитысячных десятитысячными
+
+двадцатитысячный двадцатитысячного двадцатитысячному двадцатитысячным двадцатитысячном двадцатитысячная
+двадцатитысячной двадцатитысячную двадцатитысячною двадцатитысячное двадцатитысячные двадцатитысячных
+двадцатитысячными
+
+тридцатитысячный тридцатитысячного тридцатитысячному тридцатитысячным тридцатитысячном тридцатитысячная
+тридцатитысячной тридцатитысячную тридцатитысячною тридцатитысячное тридцатитысячные тридцатитысячных
+тридцатитысячными
+
+сорокатысячный сорокатысячного сорокатысячному сорокатысячным сорокатысячном сорокатысячная
+сорокатысячной сорокатысячную сорокатысячною сорокатысячное сорокатысячные сорокатысячных
+сорокатысячными
+
+пятидесятитысячный пятидесятитысячного пятидесятитысячному пятидесятитысячным пятидесятитысячном пятидесятитысячная
+пятидесятитысячной пятидесятитысячную пятидесятитысячною пятидесятитысячное пятидесятитысячные пятидесятитысячных
+пятидесятитысячными
+
+шестидесятитысячный шестидесятитысячного шестидесятитысячному шестидесятитысячным шестидесятитысячном шестидесятитысячная
+шестидесятитысячной шестидесятитысячную шестидесятитысячною шестидесятитысячное шестидесятитысячные шестидесятитысячных
+шестидесятитысячными
+
+семидесятитысячный семидесятитысячного семидесятитысячному семидесятитысячным семидесятитысячном семидесятитысячная
+семидесятитысячной семидесятитысячную семидесятитысячною семидесятитысячное семидесятитысячные семидесятитысячных
+семидесятитысячными
+
+восьмидесятитысячный восьмидесятитысячного восьмидесятитысячному восьмидесятитысячным восьмидесятитысячном восьмидесятитысячная
+восьмидесятитысячной восьмидесятитысячную восьмидесятитысячною восьмидесятитысячное восьмидесятитысячные восьмидесятитысячных
+восьмидесятитысячными
+
+стотысячный стотысячного стотысячному стотысячным стотысячном стотысячная стотысячной стотысячную стотысячное
+стотысячные стотысячных стотысячными стотысячною
миллион миллионного миллионов миллионному миллионном миллионный миллионным миллионом миллиона миллионе миллиону
-миллионов лям млн
+миллионов
+лям ляма лямы лямом лямами лямах лямов
+млн
+
+десятимиллионная десятимиллионной десятимиллионными десятимиллионный десятимиллионным десятимиллионному
+десятимиллионными десятимиллионную десятимиллионное десятимиллионные десятимиллионных десятимиллионною
миллиард миллиардного миллиардному миллиардном миллиардный миллиардным миллиардом миллиарда миллиарде миллиарду
-миллиардов лярд млрд
+миллиардов
+лярд лярда лярды лярдом лярдами лярдах лярдов
+млрд
триллион триллионного триллионному триллионном триллионный триллионным триллионом триллиона триллионе триллиону
триллионов трлн
квадриллион квадриллионного квадриллионному квадриллионный квадриллионным квадриллионом квадриллиона квадриллионе
-квадриллиону квадриллионов квадрлн
+квадриллиону квадриллионов квадрлн
квинтиллион квинтиллионного квинтиллионному квинтиллионный квинтиллионным квинтиллионом квинтиллиона квинтиллионе
-квинтиллиону квинтиллионов квинтлн
+квинтиллиону квинтиллионов квинтлн
-i ii iii iv vi vii viii ix xi xii xiii xiv xv xvi xvii xviii xix xx xxi xxii xxiii xxiv xxv xxvi xxvii xxvii xxix
+i ii iii iv v vi vii viii ix x xi xii xiii xiv xv xvi xvii xviii xix xx xxi xxii xxiii xxiv xxv xxvi xxvii xxvii xxix
""".split()
)
)
diff --git a/spacy/lang/ru/tokenizer_exceptions.py b/spacy/lang/ru/tokenizer_exceptions.py
index f3756e26c..e1889f785 100644
--- a/spacy/lang/ru/tokenizer_exceptions.py
+++ b/spacy/lang/ru/tokenizer_exceptions.py
@@ -61,6 +61,11 @@ for abbr in [
{ORTH: "2к23", NORM: "2023"},
{ORTH: "2к24", NORM: "2024"},
{ORTH: "2к25", NORM: "2025"},
+ {ORTH: "2к26", NORM: "2026"},
+ {ORTH: "2к27", NORM: "2027"},
+ {ORTH: "2к28", NORM: "2028"},
+ {ORTH: "2к29", NORM: "2029"},
+ {ORTH: "2к30", NORM: "2030"},
]:
_exc[abbr[ORTH]] = [abbr]
@@ -268,8 +273,8 @@ for abbr in [
{ORTH: "з-ка", NORM: "заимка"},
{ORTH: "п-к", NORM: "починок"},
{ORTH: "киш.", NORM: "кишлак"},
- {ORTH: "п. ст. ", NORM: "поселок станция"},
- {ORTH: "п. ж/д ст. ", NORM: "поселок при железнодорожной станции"},
+ {ORTH: "п. ст.", NORM: "поселок станция"},
+ {ORTH: "п. ж/д ст.", NORM: "поселок при железнодорожной станции"},
{ORTH: "ж/д бл-ст", NORM: "железнодорожный блокпост"},
{ORTH: "ж/д б-ка", NORM: "железнодорожная будка"},
{ORTH: "ж/д в-ка", NORM: "железнодорожная ветка"},
@@ -280,12 +285,12 @@ for abbr in [
{ORTH: "ж/д п.п.", NORM: "железнодорожный путевой пост"},
{ORTH: "ж/д о.п.", NORM: "железнодорожный остановочный пункт"},
{ORTH: "ж/д рзд.", NORM: "железнодорожный разъезд"},
- {ORTH: "ж/д ст. ", NORM: "железнодорожная станция"},
+ {ORTH: "ж/д ст.", NORM: "железнодорожная станция"},
{ORTH: "м-ко", NORM: "местечко"},
{ORTH: "д.", NORM: "деревня"},
{ORTH: "с.", NORM: "село"},
{ORTH: "сл.", NORM: "слобода"},
- {ORTH: "ст. ", NORM: "станция"},
+ {ORTH: "ст.", NORM: "станция"},
{ORTH: "ст-ца", NORM: "станица"},
{ORTH: "у.", NORM: "улус"},
{ORTH: "х.", NORM: "хутор"},
@@ -388,8 +393,9 @@ for abbr in [
{ORTH: "прим.", NORM: "примечание"},
{ORTH: "прим.ред.", NORM: "примечание редакции"},
{ORTH: "см. также", NORM: "смотри также"},
- {ORTH: "кв.м.", NORM: "квадрантный метр"},
- {ORTH: "м2", NORM: "квадрантный метр"},
+ {ORTH: "см.", NORM: "смотри"},
+ {ORTH: "кв.м.", NORM: "квадратный метр"},
+ {ORTH: "м2", NORM: "квадратный метр"},
{ORTH: "б/у", NORM: "бывший в употреблении"},
{ORTH: "сокр.", NORM: "сокращение"},
{ORTH: "чел.", NORM: "человек"},
diff --git a/spacy/lang/sl/__init__.py b/spacy/lang/sl/__init__.py
index 9ddd676bf..0070e9fa1 100644
--- a/spacy/lang/sl/__init__.py
+++ b/spacy/lang/sl/__init__.py
@@ -1,9 +1,17 @@
+from .lex_attrs import LEX_ATTRS
+from .punctuation import TOKENIZER_INFIXES, TOKENIZER_SUFFIXES, TOKENIZER_PREFIXES
from .stop_words import STOP_WORDS
+from .tokenizer_exceptions import TOKENIZER_EXCEPTIONS
from ...language import Language, BaseDefaults
class SlovenianDefaults(BaseDefaults):
stop_words = STOP_WORDS
+ tokenizer_exceptions = TOKENIZER_EXCEPTIONS
+ prefixes = TOKENIZER_PREFIXES
+ infixes = TOKENIZER_INFIXES
+ suffixes = TOKENIZER_SUFFIXES
+ lex_attr_getters = LEX_ATTRS
class Slovenian(Language):
diff --git a/spacy/lang/sl/examples.py b/spacy/lang/sl/examples.py
new file mode 100644
index 000000000..bf483c6a4
--- /dev/null
+++ b/spacy/lang/sl/examples.py
@@ -0,0 +1,18 @@
+"""
+Example sentences to test spaCy and its language models.
+
+>>> from spacy.lang.sl.examples import sentences
+>>> docs = nlp.pipe(sentences)
+"""
+
+
+sentences = [
+ "Apple načrtuje nakup britanskega startupa za 1 bilijon dolarjev",
+ "France Prešeren je umrl 8. februarja 1849 v Kranju",
+ "Staro ljubljansko letališče Moste bo obnovila družba BTC",
+ "London je največje mesto v Združenem kraljestvu.",
+ "Kje se skrivaš?",
+ "Kdo je predsednik Francije?",
+ "Katero je glavno mesto Združenih držav Amerike?",
+ "Kdaj je bil rojen Milan Kučan?",
+]
diff --git a/spacy/lang/sl/lex_attrs.py b/spacy/lang/sl/lex_attrs.py
new file mode 100644
index 000000000..958152e37
--- /dev/null
+++ b/spacy/lang/sl/lex_attrs.py
@@ -0,0 +1,145 @@
+from ...attrs import LIKE_NUM
+from ...attrs import IS_CURRENCY
+import unicodedata
+
+
+_num_words = set(
+ """
+ nula ničla nič ena dva tri štiri pet šest sedem osem
+ devet deset enajst dvanajst trinajst štirinajst petnajst
+ šestnajst sedemnajst osemnajst devetnajst dvajset trideset štirideset
+ petdeset šestdest sedemdeset osemdeset devedeset sto tisoč
+ milijon bilijon trilijon kvadrilijon nešteto
+
+ en eden enega enemu ennem enim enih enima enimi ene eni eno
+ dveh dvema dvem dvoje trije treh trem tremi troje štirje štirih štirim štirimi
+ petih petim petimi šestih šestim šestimi sedmih sedmim sedmimi osmih osmim osmimi
+ devetih devetim devetimi desetih desetim desetimi enajstih enajstim enajstimi
+ dvanajstih dvanajstim dvanajstimi trinajstih trinajstim trinajstimi
+ šestnajstih šestnajstim šestnajstimi petnajstih petnajstim petnajstimi
+ sedemnajstih sedemnajstim sedemnajstimi osemnajstih osemnajstim osemnajstimi
+ devetnajstih devetnajstim devetnajstimi dvajsetih dvajsetim dvajsetimi
+ """.split()
+)
+
+_ordinal_words = set(
+ """
+ prvi drugi tretji četrti peti šesti sedmi osmi
+ deveti deseti enajsti dvanajsti trinajsti štirinajsti
+ petnajsti šestnajsti sedemnajsti osemnajsti devetnajsti
+ dvajseti trideseti štirideseti petdeseti šestdeseti sedemdeseti
+ osemdeseti devetdeseti stoti tisoči milijonti bilijonti
+ trilijonti kvadrilijonti nešteti
+
+ prva druga tretja četrta peta šesta sedma osma
+ deveta deseta enajsta dvanajsta trinajsta štirnajsta
+ petnajsta šestnajsta sedemnajsta osemnajsta devetnajsta
+ dvajseta trideseta štirideseta petdeseta šestdeseta sedemdeseta
+ osemdeseta devetdeseta stota tisoča milijonta bilijonta
+ trilijonta kvadrilijonta nešteta
+
+ prvo drugo tretje četrto peto šestro sedmo osmo
+ deveto deseto enajsto dvanajsto trinajsto štirnajsto
+ petnajsto šestnajsto sedemnajsto osemnajsto devetnajsto
+ dvajseto trideseto štirideseto petdeseto šestdeseto sedemdeseto
+ osemdeseto devetdeseto stoto tisočo milijonto bilijonto
+ trilijonto kvadrilijonto nešteto
+
+ prvega drugega tretjega četrtega petega šestega sedmega osmega
+ devega desetega enajstega dvanajstega trinajstega štirnajstega
+ petnajstega šestnajstega sedemnajstega osemnajstega devetnajstega
+ dvajsetega tridesetega štiridesetega petdesetega šestdesetega sedemdesetega
+ osemdesetega devetdesetega stotega tisočega milijontega bilijontega
+ trilijontega kvadrilijontega neštetega
+
+ prvemu drugemu tretjemu četrtemu petemu šestemu sedmemu osmemu devetemu desetemu
+ enajstemu dvanajstemu trinajstemu štirnajstemu petnajstemu šestnajstemu sedemnajstemu
+ osemnajstemu devetnajstemu dvajsetemu tridesetemu štiridesetemu petdesetemu šestdesetemu
+ sedemdesetemu osemdesetemu devetdesetemu stotemu tisočemu milijontemu bilijontemu
+ trilijontemu kvadrilijontemu neštetemu
+
+ prvem drugem tretjem četrtem petem šestem sedmem osmem devetem desetem
+ enajstem dvanajstem trinajstem štirnajstem petnajstem šestnajstem sedemnajstem
+ osemnajstem devetnajstem dvajsetem tridesetem štiridesetem petdesetem šestdesetem
+ sedemdesetem osemdesetem devetdesetem stotem tisočem milijontem bilijontem
+ trilijontem kvadrilijontem neštetem
+
+ prvim drugim tretjim četrtim petim šestim sedtim osmim devetim desetim
+ enajstim dvanajstim trinajstim štirnajstim petnajstim šestnajstim sedemnajstim
+ osemnajstim devetnajstim dvajsetim tridesetim štiridesetim petdesetim šestdesetim
+ sedemdesetim osemdesetim devetdesetim stotim tisočim milijontim bilijontim
+ trilijontim kvadrilijontim neštetim
+
+ prvih drugih tretjih četrthih petih šestih sedmih osmih deveth desetih
+ enajstih dvanajstih trinajstih štirnajstih petnajstih šestnajstih sedemnajstih
+ osemnajstih devetnajstih dvajsetih tridesetih štiridesetih petdesetih šestdesetih
+ sedemdesetih osemdesetih devetdesetih stotih tisočih milijontih bilijontih
+ trilijontih kvadrilijontih nešteth
+
+ prvima drugima tretjima četrtima petima šestima sedmima osmima devetima desetima
+ enajstima dvanajstima trinajstima štirnajstima petnajstima šestnajstima sedemnajstima
+ osemnajstima devetnajstima dvajsetima tridesetima štiridesetima petdesetima šestdesetima
+ sedemdesetima osemdesetima devetdesetima stotima tisočima milijontima bilijontima
+ trilijontima kvadrilijontima neštetima
+
+ prve druge četrte pete šeste sedme osme devete desete
+ enajste dvanajste trinajste štirnajste petnajste šestnajste sedemnajste
+ osemnajste devetnajste dvajsete tridesete štiridesete petdesete šestdesete
+ sedemdesete osemdesete devetdesete stote tisoče milijonte bilijonte
+ trilijonte kvadrilijonte neštete
+
+ prvimi drugimi tretjimi četrtimi petimi šestimi sedtimi osmimi devetimi desetimi
+ enajstimi dvanajstimi trinajstimi štirnajstimi petnajstimi šestnajstimi sedemnajstimi
+ osemnajstimi devetnajstimi dvajsetimi tridesetimi štiridesetimi petdesetimi šestdesetimi
+ sedemdesetimi osemdesetimi devetdesetimi stotimi tisočimi milijontimi bilijontimi
+ trilijontimi kvadrilijontimi neštetimi
+ """.split()
+)
+
+_currency_words = set(
+ """
+ evro evra evru evrom evrov evroma evrih evrom evre evri evr eur
+ cent centa centu cenom centov centoma centih centom cente centi
+ dolar dolarja dolarji dolarju dolarjem dolarjev dolarjema dolarjih dolarje usd
+ tolar tolarja tolarji tolarju tolarjem tolarjev tolarjema tolarjih tolarje tol
+ dinar dinarja dinarji dinarju dinarjem dinarjev dinarjema dinarjih dinarje din
+ funt funta funti funtu funtom funtov funtoma funtih funte gpb
+ forint forinta forinti forintu forintom forintov forintoma forintih forinte
+ zlot zlota zloti zlotu zlotom zlotov zlotoma zlotih zlote
+ rupij rupija rupiji rupiju rupijem rupijev rupijema rupijih rupije
+ jen jena jeni jenu jenom jenov jenoma jenih jene
+ kuna kuni kune kuno kun kunama kunah kunam kunami
+ marka marki marke markama markah markami
+ """.split()
+)
+
+
+def like_num(text):
+ if text.startswith(("+", "-", "±", "~")):
+ text = text[1:]
+ text = text.replace(",", "").replace(".", "")
+ if text.isdigit():
+ return True
+ if text.count("/") == 1:
+ num, denom = text.split("/")
+ if num.isdigit() and denom.isdigit():
+ return True
+ text_lower = text.lower()
+ if text_lower in _num_words:
+ return True
+ if text_lower in _ordinal_words:
+ return True
+ return False
+
+
+def is_currency(text):
+ text_lower = text.lower()
+ if text in _currency_words:
+ return True
+ for char in text:
+ if unicodedata.category(char) != "Sc":
+ return False
+ return True
+
+
+LEX_ATTRS = {LIKE_NUM: like_num, IS_CURRENCY: is_currency}
diff --git a/spacy/lang/sl/punctuation.py b/spacy/lang/sl/punctuation.py
new file mode 100644
index 000000000..b6ca1830e
--- /dev/null
+++ b/spacy/lang/sl/punctuation.py
@@ -0,0 +1,84 @@
+from ..char_classes import (
+ LIST_ELLIPSES,
+ LIST_ICONS,
+ HYPHENS,
+ LIST_PUNCT,
+ LIST_QUOTES,
+ CURRENCY,
+ UNITS,
+ PUNCT,
+ LIST_CURRENCY,
+ CONCAT_QUOTES,
+)
+from ..char_classes import CONCAT_QUOTES, ALPHA_LOWER, ALPHA_UPPER, ALPHA
+from ..char_classes import merge_chars
+from ..punctuation import TOKENIZER_PREFIXES as BASE_TOKENIZER_PREFIXES
+
+
+INCLUDE_SPECIAL = ["\\+", "\\/", "\\•", "\\¯", "\\=", "\\×"] + HYPHENS.split("|")
+
+_prefixes = INCLUDE_SPECIAL + BASE_TOKENIZER_PREFIXES
+
+_suffixes = (
+ INCLUDE_SPECIAL
+ + LIST_PUNCT
+ + LIST_ELLIPSES
+ + LIST_QUOTES
+ + LIST_ICONS
+ + [
+ r"(?<=°[FfCcKk])\.",
+ r"(?<=[0-9])(?:{c})".format(c=CURRENCY),
+ r"(?<=[0-9])(?:{u})".format(u=UNITS),
+ r"(?<=[{al}{e}{p}(?:{q})])\.".format(
+ al=ALPHA_LOWER, e=r"%²\-\+", q=CONCAT_QUOTES, p=PUNCT
+ ),
+ r"(?<=[{au}][{au}])\.".format(au=ALPHA_UPPER),
+ # split initials like J.K. Rowling
+ r"(?<=[A-Z]\.)(?:[A-Z].)",
+ ]
+)
+
+# a list of all suffixes following a hyphen that are shouldn't split (eg. BTC-jev)
+# source: Obeliks tokenizer - https://github.com/clarinsi/obeliks/blob/master/obeliks/res/TokRulesPart1.txt
+CONCAT_QUOTES = CONCAT_QUOTES.replace("'", "")
+HYPHENS_PERMITTED = (
+ "((a)|(evemu)|(evskega)|(i)|(jevega)|(jevska)|(jevskimi)|(jinemu)|(oma)|(ovim)|"
+ "(ovski)|(e)|(evi)|(evskem)|(ih)|(jevem)|(jevske)|(jevsko)|(jini)|(ov)|(ovima)|"
+ "(ovskih)|(em)|(evih)|(evskemu)|(ja)|(jevemu)|(jevskega)|(ji)|(jinih)|(ova)|"
+ "(ovimi)|(ovskim)|(ema)|(evim)|(evski)|(je)|(jevi)|(jevskem)|(jih)|(jinim)|"
+ "(ove)|(ovo)|(ovskima)|(ev)|(evima)|(evskih)|(jem)|(jevih)|(jevskemu)|(jin)|"
+ "(jinima)|(ovega)|(ovska)|(ovskimi)|(eva)|(evimi)|(evskim)|(jema)|(jevim)|"
+ "(jevski)|(jina)|(jinimi)|(ovem)|(ovske)|(ovsko)|(eve)|(evo)|(evskima)|(jev)|"
+ "(jevima)|(jevskih)|(jine)|(jino)|(ovemu)|(ovskega)|(u)|(evega)|(evska)|"
+ "(evskimi)|(jeva)|(jevimi)|(jevskim)|(jinega)|(ju)|(ovi)|(ovskem)|(evem)|"
+ "(evske)|(evsko)|(jeve)|(jevo)|(jevskima)|(jinem)|(om)|(ovih)|(ovskemu)|"
+ "(ovec)|(ovca)|(ovcu)|(ovcem)|(ovcev)|(ovcema)|(ovcih)|(ovci)|(ovce)|(ovcimi)|"
+ "(evec)|(evca)|(evcu)|(evcem)|(evcev)|(evcema)|(evcih)|(evci)|(evce)|(evcimi)|"
+ "(jevec)|(jevca)|(jevcu)|(jevcem)|(jevcev)|(jevcema)|(jevcih)|(jevci)|(jevce)|"
+ "(jevcimi)|(ovka)|(ovke)|(ovki)|(ovko)|(ovk)|(ovkama)|(ovkah)|(ovkam)|(ovkami)|"
+ "(evka)|(evke)|(evki)|(evko)|(evk)|(evkama)|(evkah)|(evkam)|(evkami)|(jevka)|"
+ "(jevke)|(jevki)|(jevko)|(jevk)|(jevkama)|(jevkah)|(jevkam)|(jevkami)|(timi)|"
+ "(im)|(ima)|(a)|(imi)|(e)|(o)|(ega)|(ti)|(em)|(tih)|(emu)|(tim)|(i)|(tima)|"
+ "(ih)|(ta)|(te)|(to)|(tega)|(tem)|(temu))"
+)
+
+_infixes = (
+ LIST_ELLIPSES
+ + LIST_ICONS
+ + [
+ r"(?<=[0-9])[+\-\*^](?=[0-9-])",
+ r"(?<=[{al}{q}])\.(?=[{au}{q}])".format(
+ al=ALPHA_LOWER, au=ALPHA_UPPER, q=CONCAT_QUOTES
+ ),
+ r"(?<=[{a}]),(?=[{a}])".format(a=ALPHA),
+ r"(?<=[{a}0-9])(?:{h})(?!{hp}$)(?=[{a}])".format(
+ a=ALPHA, h=HYPHENS, hp=HYPHENS_PERMITTED
+ ),
+ r"(?<=[{a}0-9])[:<>=/](?=[{a}])".format(a=ALPHA),
+ ]
+)
+
+
+TOKENIZER_PREFIXES = _prefixes
+TOKENIZER_SUFFIXES = _suffixes
+TOKENIZER_INFIXES = _infixes
diff --git a/spacy/lang/sl/stop_words.py b/spacy/lang/sl/stop_words.py
index c9004ed5d..8491efcb5 100644
--- a/spacy/lang/sl/stop_words.py
+++ b/spacy/lang/sl/stop_words.py
@@ -1,326 +1,84 @@
# Source: https://github.com/stopwords-iso/stopwords-sl
-# Removed various words that are not normally considered stop words, such as months.
STOP_WORDS = set(
"""
-a
-ali
-b
-bi
-bil
-bila
-bile
-bili
-bilo
-biti
-blizu
-bo
-bodo
-bolj
-bom
-bomo
-boste
-bova
-boš
-brez
-c
-cel
-cela
-celi
-celo
-d
-da
-daleč
-dan
-danes
-do
-dober
-dobra
-dobri
-dobro
-dokler
-dol
-dovolj
-e
-eden
-en
-ena
-ene
-eni
-enkrat
-eno
-etc.
+a ali
+
+b bi bil bila bile bili bilo biti blizu bo bodo bojo bolj bom bomo
+boste bova boš brez
+
+c cel cela celi celo
+
+č če često četrta četrtek četrti četrto čez čigav
+
+d da daleč dan danes datum deset deseta deseti deseto devet
+deveta deveti deveto do dober dobra dobri dobro dokler dol dolg
+dolga dolgi dovolj drug druga drugi drugo dva dve
+
+e eden en ena ene eni enkrat eno etc.
+
f
-g
-g.
-ga
-ga.
-gor
-gospa
-gospod
-h
-halo
-i
-idr.
-ii
-iii
-in
-iv
-ix
-iz
-j
-jaz
-je
-ji
-jih
-jim
-jo
-k
-kadarkoli
-kaj
-kajti
-kako
-kakor
-kamor
-kamorkoli
-kar
-karkoli
-katerikoli
-kdaj
-kdo
-kdorkoli
-ker
-ki
-kje
-kjer
-kjerkoli
-ko
-koderkoli
-koga
-komu
-kot
-l
-le
-lep
-lepa
-lepe
-lepi
-lepo
-m
-manj
-me
-med
-medtem
-mene
-mi
-midva
-midve
-mnogo
-moj
-moja
-moje
-mora
-morajo
-moram
-moramo
-morate
-moraš
-morem
-mu
-n
-na
-nad
-naj
-najina
-najino
-najmanj
-naju
-največ
-nam
-nas
-nato
-nazaj
-naš
-naša
-naše
-ne
-nedavno
-nek
-neka
-nekaj
-nekatere
-nekateri
-nekatero
-nekdo
-neke
-nekega
-neki
-nekje
-neko
-nekoga
-nekoč
-ni
-nikamor
-nikdar
-nikjer
-nikoli
-nič
-nje
-njega
-njegov
-njegova
-njegovo
-njej
-njemu
-njen
-njena
-njeno
-nji
-njih
-njihov
-njihova
-njihovo
-njiju
-njim
-njo
-njun
-njuna
-njuno
-no
-nocoj
-npr.
-o
-ob
-oba
-obe
-oboje
-od
-okoli
-on
-onadva
-one
-oni
-onidve
-oz.
-p
-pa
-po
-pod
-pogosto
-poleg
-ponavadi
-ponovno
-potem
-povsod
-prbl.
-precej
-pred
-prej
-preko
-pri
-pribl.
-približno
-proti
-r
-redko
-res
-s
-saj
-sam
-sama
-same
-sami
-samo
-se
-sebe
-sebi
-sedaj
-sem
-seveda
-si
-sicer
-skoraj
-skozi
-smo
-so
-spet
-sta
-ste
-sva
-t
-ta
-tak
-taka
-take
-taki
-tako
-takoj
-tam
-te
-tebe
-tebi
-tega
-ti
-tista
-tiste
-tisti
-tisto
-tj.
-tja
-to
-toda
-tu
-tudi
-tukaj
-tvoj
-tvoja
-tvoje
+
+g g. ga ga. gor gospa gospod
+
+h halo
+
+i idr. ii iii in iv ix iz
+
+j jaz je ji jih jim jo jutri
+
+k kadarkoli kaj kajti kako kakor kamor kamorkoli kar karkoli
+katerikoli kdaj kdo kdorkoli ker ki kje kjer kjerkoli
+ko koder koderkoli koga komu kot kratek kratka kratke kratki
+
+l lahka lahke lahki lahko le lep lepa lepe lepi lepo leto
+
+m majhen majhna majhni malce malo manj me med medtem mene
+mesec mi midva midve mnogo moj moja moje mora morajo moram
+moramo morate moraš morem mu
+
+n na nad naj najina najino najmanj naju največ nam narobe
+nas nato nazaj naš naša naše ne nedavno nedelja nek neka
+nekaj nekatere nekateri nekatero nekdo neke nekega neki
+nekje neko nekoga nekoč ni nikamor nikdar nikjer nikoli
+nič nje njega njegov njegova njegovo njej njemu njen
+njena njeno nji njih njihov njihova njihovo njiju njim
+njo njun njuna njuno no nocoj npr.
+
+o ob oba obe oboje od odprt odprta odprti okoli on
+onadva one oni onidve osem osma osmi osmo oz.
+
+p pa pet peta petek peti peto po pod pogosto poleg poln
+polna polni polno ponavadi ponedeljek ponovno potem
+povsod pozdravljen pozdravljeni prav prava prave pravi
+pravo prazen prazna prazno prbl. precej pred prej preko
+pri pribl. približno primer pripravljen pripravljena
+pripravljeni proti prva prvi prvo
+
+r ravno redko res reč
+
+s saj sam sama same sami samo se sebe sebi sedaj sedem
+sedma sedmi sedmo sem seveda si sicer skoraj skozi slab sm
+so sobota spet sreda srednja srednji sta ste stran stvar sva
+
+š šest šesta šesti šesto štiri
+
+t ta tak taka take taki tako takoj tam te tebe tebi tega
+težak težka težki težko ti tista tiste tisti tisto tj.
+tja to toda torek tretja tretje tretji tri tu tudi tukaj
+tvoj tvoja tvoje
+
u
-v
-vaju
-vam
-vas
-vaš
-vaša
-vaše
-ve
-vedno
-vendar
-ves
-več
-vi
-vidva
-vii
-viii
-vsa
-vsaj
-vsak
-vsaka
-vsakdo
-vsake
-vsaki
-vsakomur
-vse
-vsega
-vsi
-vso
-včasih
-x
-z
-za
-zadaj
-zadnji
-zakaj
-zdaj
-zelo
-zunaj
-č
-če
-često
-čez
-čigav
-š
-ž
-že
+
+v vaju vam vas vaš vaša vaše ve vedno velik velika veliki
+veliko vendar ves več vi vidva vii viii visok visoka visoke
+visoki vsa vsaj vsak vsaka vsakdo vsake vsaki vsakomur vse
+vsega vsi vso včasih včeraj
+
+x
+
+z za zadaj zadnji zakaj zaprta zaprti zaprto zdaj zelo zunaj
+
+ž že
""".split()
)
diff --git a/spacy/lang/sl/tokenizer_exceptions.py b/spacy/lang/sl/tokenizer_exceptions.py
new file mode 100644
index 000000000..3d4109228
--- /dev/null
+++ b/spacy/lang/sl/tokenizer_exceptions.py
@@ -0,0 +1,272 @@
+from typing import Dict, List
+from ..tokenizer_exceptions import BASE_EXCEPTIONS
+from ...symbols import ORTH, NORM
+from ...util import update_exc
+
+_exc: Dict[str, List[Dict]] = {}
+
+_other_exc = {
+ "t.i.": [{ORTH: "t.", NORM: "tako"}, {ORTH: "i.", NORM: "imenovano"}],
+ "t.j.": [{ORTH: "t.", NORM: "to"}, {ORTH: "j.", NORM: "je"}],
+ "T.j.": [{ORTH: "T.", NORM: "to"}, {ORTH: "j.", NORM: "je"}],
+ "d.o.o.": [
+ {ORTH: "d.", NORM: "družba"},
+ {ORTH: "o.", NORM: "omejeno"},
+ {ORTH: "o.", NORM: "odgovornostjo"},
+ ],
+ "D.O.O.": [
+ {ORTH: "D.", NORM: "družba"},
+ {ORTH: "O.", NORM: "omejeno"},
+ {ORTH: "O.", NORM: "odgovornostjo"},
+ ],
+ "d.n.o.": [
+ {ORTH: "d.", NORM: "družba"},
+ {ORTH: "n.", NORM: "neomejeno"},
+ {ORTH: "o.", NORM: "odgovornostjo"},
+ ],
+ "D.N.O.": [
+ {ORTH: "D.", NORM: "družba"},
+ {ORTH: "N.", NORM: "neomejeno"},
+ {ORTH: "O.", NORM: "odgovornostjo"},
+ ],
+ "d.d.": [{ORTH: "d.", NORM: "delniška"}, {ORTH: "d.", NORM: "družba"}],
+ "D.D.": [{ORTH: "D.", NORM: "delniška"}, {ORTH: "D.", NORM: "družba"}],
+ "s.p.": [{ORTH: "s.", NORM: "samostojni"}, {ORTH: "p.", NORM: "podjetnik"}],
+ "S.P.": [{ORTH: "S.", NORM: "samostojni"}, {ORTH: "P.", NORM: "podjetnik"}],
+ "l.r.": [{ORTH: "l.", NORM: "lastno"}, {ORTH: "r.", NORM: "ročno"}],
+ "le-te": [{ORTH: "le"}, {ORTH: "-"}, {ORTH: "te"}],
+ "Le-te": [{ORTH: "Le"}, {ORTH: "-"}, {ORTH: "te"}],
+ "le-ti": [{ORTH: "le"}, {ORTH: "-"}, {ORTH: "ti"}],
+ "Le-ti": [{ORTH: "Le"}, {ORTH: "-"}, {ORTH: "ti"}],
+ "le-to": [{ORTH: "le"}, {ORTH: "-"}, {ORTH: "to"}],
+ "Le-to": [{ORTH: "Le"}, {ORTH: "-"}, {ORTH: "to"}],
+ "le-ta": [{ORTH: "le"}, {ORTH: "-"}, {ORTH: "ta"}],
+ "Le-ta": [{ORTH: "Le"}, {ORTH: "-"}, {ORTH: "ta"}],
+ "le-tega": [{ORTH: "le"}, {ORTH: "-"}, {ORTH: "tega"}],
+ "Le-tega": [{ORTH: "Le"}, {ORTH: "-"}, {ORTH: "tega"}],
+}
+
+_exc.update(_other_exc)
+
+
+for exc_data in [
+ {ORTH: "adm.", NORM: "administracija"},
+ {ORTH: "aer.", NORM: "aeronavtika"},
+ {ORTH: "agr.", NORM: "agronomija"},
+ {ORTH: "amer.", NORM: "ameriško"},
+ {ORTH: "anat.", NORM: "anatomija"},
+ {ORTH: "angl.", NORM: "angleški"},
+ {ORTH: "ant.", NORM: "antonim"},
+ {ORTH: "antr.", NORM: "antropologija"},
+ {ORTH: "apr.", NORM: "april"},
+ {ORTH: "arab.", NORM: "arabsko"},
+ {ORTH: "arheol.", NORM: "arheologija"},
+ {ORTH: "arhit.", NORM: "arhitektura"},
+ {ORTH: "avg.", NORM: "avgust"},
+ {ORTH: "avstr.", NORM: "avstrijsko"},
+ {ORTH: "avt.", NORM: "avtomobilizem"},
+ {ORTH: "bibl.", NORM: "biblijsko"},
+ {ORTH: "biokem.", NORM: "biokemija"},
+ {ORTH: "biol.", NORM: "biologija"},
+ {ORTH: "bolg.", NORM: "bolgarski"},
+ {ORTH: "bot.", NORM: "botanika"},
+ {ORTH: "cit.", NORM: "citat"},
+ {ORTH: "daj.", NORM: "dajalnik"},
+ {ORTH: "del.", NORM: "deležnik"},
+ {ORTH: "ed.", NORM: "ednina"},
+ {ORTH: "etn.", NORM: "etnografija"},
+ {ORTH: "farm.", NORM: "farmacija"},
+ {ORTH: "filat.", NORM: "filatelija"},
+ {ORTH: "filoz.", NORM: "filozofija"},
+ {ORTH: "fin.", NORM: "finančništvo"},
+ {ORTH: "fiz.", NORM: "fizika"},
+ {ORTH: "fot.", NORM: "fotografija"},
+ {ORTH: "fr.", NORM: "francoski"},
+ {ORTH: "friz.", NORM: "frizerstvo"},
+ {ORTH: "gastr.", NORM: "gastronomija"},
+ {ORTH: "geogr.", NORM: "geografija"},
+ {ORTH: "geol.", NORM: "geologija"},
+ {ORTH: "geom.", NORM: "geometrija"},
+ {ORTH: "germ.", NORM: "germanski"},
+ {ORTH: "gl.", NORM: "glej"},
+ {ORTH: "glag.", NORM: "glagolski"},
+ {ORTH: "glasb.", NORM: "glasba"},
+ {ORTH: "gled.", NORM: "gledališče"},
+ {ORTH: "gost.", NORM: "gostinstvo"},
+ {ORTH: "gozd.", NORM: "gozdarstvo"},
+ {ORTH: "gr.", NORM: "grški"},
+ {ORTH: "grad.", NORM: "gradbeništvo"},
+ {ORTH: "hebr.", NORM: "hebrejsko"},
+ {ORTH: "hrv.", NORM: "hrvaško"},
+ {ORTH: "ide.", NORM: "indoevropsko"},
+ {ORTH: "igr.", NORM: "igre"},
+ {ORTH: "im.", NORM: "imenovalnik"},
+ {ORTH: "iron.", NORM: "ironično"},
+ {ORTH: "it.", NORM: "italijanski"},
+ {ORTH: "itd.", NORM: "in tako dalje"},
+ {ORTH: "itn.", NORM: "in tako naprej"},
+ {ORTH: "ipd.", NORM: "in podobno"},
+ {ORTH: "jap.", NORM: "japonsko"},
+ {ORTH: "jul.", NORM: "julij"},
+ {ORTH: "jun.", NORM: "junij"},
+ {ORTH: "kit.", NORM: "kitajsko"},
+ {ORTH: "knj.", NORM: "knjižno"},
+ {ORTH: "knjiž.", NORM: "knjižno"},
+ {ORTH: "kor.", NORM: "koreografija"},
+ {ORTH: "lat.", NORM: "latinski"},
+ {ORTH: "les.", NORM: "lesna stroka"},
+ {ORTH: "lingv.", NORM: "lingvistika"},
+ {ORTH: "lit.", NORM: "literarni"},
+ {ORTH: "ljubk.", NORM: "ljubkovalno"},
+ {ORTH: "lov.", NORM: "lovstvo"},
+ {ORTH: "m.", NORM: "moški"},
+ {ORTH: "mak.", NORM: "makedonski"},
+ {ORTH: "mar.", NORM: "marec"},
+ {ORTH: "mat.", NORM: "matematika"},
+ {ORTH: "med.", NORM: "medicina"},
+ {ORTH: "meh.", NORM: "mehiško"},
+ {ORTH: "mest.", NORM: "mestnik"},
+ {ORTH: "mdr.", NORM: "med drugim"},
+ {ORTH: "min.", NORM: "mineralogija"},
+ {ORTH: "mitol.", NORM: "mitologija"},
+ {ORTH: "mn.", NORM: "množina"},
+ {ORTH: "mont.", NORM: "montanistika"},
+ {ORTH: "muz.", NORM: "muzikologija"},
+ {ORTH: "nam.", NORM: "namenilnik"},
+ {ORTH: "nar.", NORM: "narečno"},
+ {ORTH: "nav.", NORM: "navadno"},
+ {ORTH: "nedol.", NORM: "nedoločnik"},
+ {ORTH: "nedov.", NORM: "nedovršni"},
+ {ORTH: "neprav.", NORM: "nepravilno"},
+ {ORTH: "nepreh.", NORM: "neprehodno"},
+ {ORTH: "neskl.", NORM: "nesklonljiv(o)"},
+ {ORTH: "nestrok.", NORM: "nestrokovno"},
+ {ORTH: "num.", NORM: "numizmatika"},
+ {ORTH: "npr.", NORM: "na primer"},
+ {ORTH: "obrt.", NORM: "obrtništvo"},
+ {ORTH: "okt.", NORM: "oktober"},
+ {ORTH: "or.", NORM: "orodnik"},
+ {ORTH: "os.", NORM: "oseba"},
+ {ORTH: "otr.", NORM: "otroško"},
+ {ORTH: "oz.", NORM: "oziroma"},
+ {ORTH: "pal.", NORM: "paleontologija"},
+ {ORTH: "papir.", NORM: "papirništvo"},
+ {ORTH: "ped.", NORM: "pedagogika"},
+ {ORTH: "pisar.", NORM: "pisarniško"},
+ {ORTH: "pog.", NORM: "pogovorno"},
+ {ORTH: "polit.", NORM: "politika"},
+ {ORTH: "polj.", NORM: "poljsko"},
+ {ORTH: "poljud.", NORM: "poljudno"},
+ {ORTH: "preg.", NORM: "pregovor"},
+ {ORTH: "preh.", NORM: "prehodno"},
+ {ORTH: "pren.", NORM: "preneseno"},
+ {ORTH: "prid.", NORM: "pridevnik"},
+ {ORTH: "prim.", NORM: "primerjaj"},
+ {ORTH: "prisl.", NORM: "prislov"},
+ {ORTH: "psih.", NORM: "psihologija"},
+ {ORTH: "psiht.", NORM: "psihiatrija"},
+ {ORTH: "rad.", NORM: "radiotehnika"},
+ {ORTH: "rač.", NORM: "računalništvo"},
+ {ORTH: "rib.", NORM: "ribištvo"},
+ {ORTH: "rod.", NORM: "rodilnik"},
+ {ORTH: "rus.", NORM: "rusko"},
+ {ORTH: "s.", NORM: "srednji"},
+ {ORTH: "sam.", NORM: "samostalniški"},
+ {ORTH: "sed.", NORM: "sedanjik"},
+ {ORTH: "sep.", NORM: "september"},
+ {ORTH: "slabš.", NORM: "slabšalno"},
+ {ORTH: "slovan.", NORM: "slovansko"},
+ {ORTH: "slovaš.", NORM: "slovaško"},
+ {ORTH: "srb.", NORM: "srbsko"},
+ {ORTH: "star.", NORM: "starinsko"},
+ {ORTH: "stil.", NORM: "stilno"},
+ {ORTH: "sv.", NORM: "svet(i)"},
+ {ORTH: "teh.", NORM: "tehnika"},
+ {ORTH: "tisk.", NORM: "tiskarstvo"},
+ {ORTH: "tj.", NORM: "to je"},
+ {ORTH: "tož.", NORM: "tožilnik"},
+ {ORTH: "trg.", NORM: "trgovina"},
+ {ORTH: "ukr.", NORM: "ukrajinski"},
+ {ORTH: "um.", NORM: "umetnost"},
+ {ORTH: "vel.", NORM: "velelnik"},
+ {ORTH: "vet.", NORM: "veterina"},
+ {ORTH: "vez.", NORM: "veznik"},
+ {ORTH: "vn.", NORM: "visokonemško"},
+ {ORTH: "voj.", NORM: "vojska"},
+ {ORTH: "vrtn.", NORM: "vrtnarstvo"},
+ {ORTH: "vulg.", NORM: "vulgarno"},
+ {ORTH: "vznes.", NORM: "vzneseno"},
+ {ORTH: "zal.", NORM: "založništvo"},
+ {ORTH: "zastar.", NORM: "zastarelo"},
+ {ORTH: "zgod.", NORM: "zgodovina"},
+ {ORTH: "zool.", NORM: "zoologija"},
+ {ORTH: "čeb.", NORM: "čebelarstvo"},
+ {ORTH: "češ.", NORM: "češki"},
+ {ORTH: "člov.", NORM: "človeškost"},
+ {ORTH: "šah.", NORM: "šahovski"},
+ {ORTH: "šalj.", NORM: "šaljivo"},
+ {ORTH: "šp.", NORM: "španski"},
+ {ORTH: "špan.", NORM: "špansko"},
+ {ORTH: "šport.", NORM: "športni"},
+ {ORTH: "štev.", NORM: "števnik"},
+ {ORTH: "šved.", NORM: "švedsko"},
+ {ORTH: "švic.", NORM: "švicarsko"},
+ {ORTH: "ž.", NORM: "ženski"},
+ {ORTH: "žarg.", NORM: "žargonsko"},
+ {ORTH: "žel.", NORM: "železnica"},
+ {ORTH: "živ.", NORM: "živost"},
+]:
+ _exc[exc_data[ORTH]] = [exc_data]
+
+
+abbrv = """
+Co. Ch. DIPL. DR. Dr. Ev. Inc. Jr. Kr. Mag. M. MR. Mr. Mt. Murr. Npr. OZ.
+Opr. Osn. Prim. Roj. ST. Sim. Sp. Sred. St. Sv. Škofl. Tel. UR. Zb.
+a. aa. ab. abc. abit. abl. abs. abt. acc. accel. add. adj. adv. aet. afr. akad. al. alban. all. alleg.
+alp. alt. alter. alžir. am. an. andr. ang. anh. anon. ans. antrop. apoc. app. approx. apt. ar. arc. arch.
+arh. arr. as. asist. assist. assoc. asst. astr. attn. aug. avstral. az. b. bab. bal. bbl. bd. belg. bioinf.
+biomed. bk. bl. bn. borg. bp. br. braz. brit. bros. broš. bt. bu. c. ca. cal. can. cand. cantab. cap. capt.
+cat. cath. cc. cca. cd. cdr. cdre. cent. cerkv. cert. cf. cfr. ch. chap. chem. chr. chs. cic. circ. civ. cl.
+cm. cmd. cnr. co. cod. col. coll. colo. com. comp. con. conc. cond. conn. cons. cont. coop. corr. cost. cp.
+cpl. cr. crd. cres. cresc. ct. cu. d. dan. dat. davč. ddr. dec. ded. def. dem. dent. dept. dia. dip. dipl.
+dir. disp. diss. div. do. doc. dok. dol. doo. dop. dott. dr. dram. druž. družb. drž. dt. duh. dur. dvr. dwt. e.
+ea. ecc. eccl. eccles. econ. edn. egipt. egr. ekon. eksp. el. em. enc. eng. eo. ep. err. esp. esq. est.
+et. etc. etnogr. etnol. ev. evfem. evr. ex. exc. excl. exp. expl. ext. exx. f. fa. facs. fak. faks. fas.
+fasc. fco. fcp. feb. febr. fec. fed. fem. ff. fff. fid. fig. fil. film. fiziol. fiziot. flam. fm. fo. fol. folk.
+frag. fran. franc. fsc. g. ga. gal. gdč. ge. gen. geod. geog. geotehnol. gg. gimn. glas. glav. gnr. go. gor.
+gosp. gp. graf. gram. gren. grš. gs. h. hab. hf. hist. ho. hort. i. ia. ib. ibid. id. idr. idridr. ill. imen.
+imp. impf. impr. in. inc. incl. ind. indus. inf. inform. ing. init. ins. int. inv. inšp. inštr. inž. is. islam.
+ist. ital. iur. iz. izbr. izd. izg. izgr. izr. izv. j. jak. jam. jan. jav. je. jez. jr. jsl. jud. jug.
+jugoslovan. jur. juž. jv. jz. k. kal. kan. kand. kat. kdo. kem. kip. kmet. kol. kom. komp. konf. kont. kost. kov.
+kp. kpfw. kr. kraj. krat. kub. kult. kv. kval. l. la. lab. lb. ld. let. lib. lik. litt. lj. ljud. ll. loc. log.
+loč. lt. ma. madž. mag. manag. manjš. masc. mass. mater. max. maxmax. mb. md. mech. medic. medij. medn.
+mehč. mem. menedž. mes. mess. metal. meteor. meteorol. mex. mi. mikr. mil. minn. mio. misc. miss. mit. mk.
+mkt. ml. mlad. mlle. mlr. mm. mme. množ. mo. moj. moš. možn. mr. mrd. mrs. ms. msc. msgr. mt. murr. mus. mut.
+n. na. nad. nadalj. nadom. nagl. nakl. namer. nan. naniz. nasl. nat. navt. nač. ned. nem. nik. nizoz. nm. nn.
+no. nom. norv. notr. nov. novogr. ns. o. ob. obd. obj. oblač. obl. oblik. obr. obraz. obs. obst. obt. obč. oc.
+oct. od. odd. odg. odn. odst. odv. oec. off. ok. okla. okr. ont. oo. op. opis. opp. opr. orch. ord. ore. oreg.
+org. orient. orig. ork. ort. oseb. osn. ot. ozir. ošk. p. pag. par. para. parc. parl. part. past. pat. pdk.
+pen. perf. pert. perz. pesn. pet. pev. pf. pfc. ph. pharm. phil. pis. pl. po. pod. podr. podaljš. pogl. pogoj. pojm.
+pok. pokr. pol. poljed. poljub. polu. pom. pomen. pon. ponov. pop. por. port. pos. posl. posn. pov. pp. ppl. pr.
+praet. prav. pravopis. pravosl. preb. pred. predl. predm. predp. preds. pref. pregib. prel. prem. premen. prep.
+pres. pret. prev. pribl. prih. pril. primerj. primor. prip. pripor. prir. prist. priv. proc. prof. prog. proiz.
+prom. pron. prop. prot. protest. prov. ps. pss. pt. publ. pz. q. qld. qu. quad. que. r. racc. rastl. razgl.
+razl. razv. rd. red. ref. reg. rel. relig. rep. repr. rer. resp. rest. ret. rev. revol. rež. rim. rist. rkp. rm.
+roj. rom. romun. rp. rr. rt. rud. ruš. ry. sal. samogl. san. sc. scen. sci. scr. sdv. seg. sek. sen. sept. ser.
+sev. sg. sgt. sh. sig. sigg. sign. sim. sin. sing. sinh. skand. skl. sklad. sklanj. sklep. skr. sl. slik. slov.
+slovak. slovn. sn. so. sob. soc. sociol. sod. sopomen. sopr. sor. sov. sovj. sp. spec. spl. spr. spreg. sq. sr.
+sre. sred. sredoz. srh. ss. ssp. st. sta. stan. stanstar. stcsl. ste. stim. stol. stom. str. stroj. strok. stsl.
+stud. sup. supl. suppl. svet. sz. t. tab. tech. ted. tehn. tehnol. tek. teks. tekst. tel. temp. ten. teol. ter.
+term. test. th. theol. tim. tip. tisočl. tit. tl. tol. tolmač. tom. tor. tov. tr. trad. traj. trans. tren.
+trib. tril. trop. trp. trž. ts. tt. tu. tur. turiz. tvor. tvorb. tč. u. ul. umet. un. univ. up. upr. ur. urad.
+us. ust. utr. v. va. val. var. varn. ven. ver. verb. vest. vezal. vic. vis. viv. viz. viš. vod. vok. vol. vpr.
+vrst. vrstil. vs. vv. vzd. vzg. vzh. vzor. w. wed. wg. wk. x. y. z. zah. zaim. zak. zap. zasl. zavar. zač. zb.
+združ. zg. zn. znan. znanstv. zoot. zun. zv. zvd. á. é. ć. č. čas. čet. čl. člen. čustv. đ. ľ. ł. ş. ŠT. š. šir.
+škofl. škot. šol. št. števil. štud. ů. ű. žen. žival.
+""".split()
+
+for orth in abbrv:
+ _exc[orth] = [{ORTH: orth}]
+
+
+TOKENIZER_EXCEPTIONS = update_exc(BASE_EXCEPTIONS, _exc)
diff --git a/spacy/lang/tr/lex_attrs.py b/spacy/lang/tr/lex_attrs.py
index f7416837d..6d9f4f388 100644
--- a/spacy/lang/tr/lex_attrs.py
+++ b/spacy/lang/tr/lex_attrs.py
@@ -53,7 +53,7 @@ _ordinal_words = [
"doksanıncı",
"yüzüncü",
"bininci",
- "mliyonuncu",
+ "milyonuncu",
"milyarıncı",
"trilyonuncu",
"katrilyonuncu",
diff --git a/spacy/lang/uk/__init__.py b/spacy/lang/uk/__init__.py
index 21f9649f2..bfea9ff69 100644
--- a/spacy/lang/uk/__init__.py
+++ b/spacy/lang/uk/__init__.py
@@ -6,6 +6,8 @@ from .tokenizer_exceptions import TOKENIZER_EXCEPTIONS
from .stop_words import STOP_WORDS
from .lex_attrs import LEX_ATTRS
from .lemmatizer import UkrainianLemmatizer
+from ..punctuation import COMBINING_DIACRITICS_TOKENIZER_INFIXES
+from ..punctuation import COMBINING_DIACRITICS_TOKENIZER_SUFFIXES
from ...language import Language, BaseDefaults
@@ -13,6 +15,8 @@ class UkrainianDefaults(BaseDefaults):
tokenizer_exceptions = TOKENIZER_EXCEPTIONS
lex_attr_getters = LEX_ATTRS
stop_words = STOP_WORDS
+ suffixes = COMBINING_DIACRITICS_TOKENIZER_SUFFIXES
+ infixes = COMBINING_DIACRITICS_TOKENIZER_INFIXES
class Ukrainian(Language):
@@ -25,7 +29,7 @@ class Ukrainian(Language):
assigns=["token.lemma"],
default_config={
"model": None,
- "mode": "pymorphy2",
+ "mode": "pymorphy3",
"overwrite": False,
"scorer": {"@scorers": "spacy.lemmatizer_scorer.v1"},
},
diff --git a/spacy/lang/uk/lemmatizer.py b/spacy/lang/uk/lemmatizer.py
index a8bc56057..37015cc2a 100644
--- a/spacy/lang/uk/lemmatizer.py
+++ b/spacy/lang/uk/lemmatizer.py
@@ -14,11 +14,11 @@ class UkrainianLemmatizer(RussianLemmatizer):
model: Optional[Model],
name: str = "lemmatizer",
*,
- mode: str = "pymorphy2",
+ mode: str = "pymorphy3",
overwrite: bool = False,
scorer: Optional[Callable] = lemmatizer_score,
) -> None:
- if mode == "pymorphy2":
+ if mode in {"pymorphy2", "pymorphy2_lookup"}:
try:
from pymorphy2 import MorphAnalyzer
except ImportError:
@@ -29,6 +29,17 @@ class UkrainianLemmatizer(RussianLemmatizer):
) from None
if getattr(self, "_morph", None) is None:
self._morph = MorphAnalyzer(lang="uk")
+ elif mode in {"pymorphy3", "pymorphy3_lookup"}:
+ try:
+ from pymorphy3 import MorphAnalyzer
+ except ImportError:
+ raise ImportError(
+ "The Ukrainian lemmatizer mode 'pymorphy3' requires the "
+ "pymorphy3 library and dictionaries. Install them with: "
+ "pip install pymorphy3 pymorphy3-dicts-uk"
+ ) from None
+ if getattr(self, "_morph", None) is None:
+ self._morph = MorphAnalyzer(lang="uk")
super().__init__(
vocab, model, name, mode=mode, overwrite=overwrite, scorer=scorer
)
diff --git a/spacy/lang/vi/lex_attrs.py b/spacy/lang/vi/lex_attrs.py
index 33a3745cc..0cbda4ffb 100644
--- a/spacy/lang/vi/lex_attrs.py
+++ b/spacy/lang/vi/lex_attrs.py
@@ -2,22 +2,29 @@ from ...attrs import LIKE_NUM
_num_words = [
- "không",
- "một",
- "hai",
- "ba",
- "bốn",
- "năm",
- "sáu",
- "bảy",
- "bẩy",
- "tám",
- "chín",
- "mười",
- "chục",
- "trăm",
- "nghìn",
- "tỷ",
+ "không", # Zero
+ "một", # One
+ "mốt", # Also one, irreplacable in niché cases for unit digit such as "51"="năm mươi mốt"
+ "hai", # Two
+ "ba", # Three
+ "bốn", # Four
+ "tư", # Also four, used in certain cases for unit digit such as "54"="năm mươi tư"
+ "năm", # Five
+ "lăm", # Also five, irreplacable in niché cases for unit digit such as "55"="năm mươi lăm"
+ "sáu", # Six
+ "bảy", # Seven
+ "bẩy", # Also seven, old fashioned
+ "tám", # Eight
+ "chín", # Nine
+ "mười", # Ten
+ "chục", # Also ten, used for counting in tens such as "20 eggs"="hai chục trứng"
+ "trăm", # Hundred
+ "nghìn", # Thousand
+ "ngàn", # Also thousand, used in the south
+ "vạn", # Ten thousand
+ "triệu", # Million
+ "tỷ", # Billion
+ "tỉ", # Also billion, used in combinatorics such as "tỉ_phú"="billionaire"
]
diff --git a/spacy/language.py b/spacy/language.py
index bab403f0e..e0abfd5e7 100644
--- a/spacy/language.py
+++ b/spacy/language.py
@@ -10,6 +10,7 @@ from contextlib import contextmanager
from copy import deepcopy
from pathlib import Path
import warnings
+
from thinc.api import get_current_ops, Config, CupyOps, Optimizer
import srsly
import multiprocessing as mp
@@ -24,7 +25,7 @@ from .pipe_analysis import validate_attrs, analyze_pipes, print_pipe_analysis
from .training import Example, validate_examples
from .training.initialize import init_vocab, init_tok2vec
from .scorer import Scorer
-from .util import registry, SimpleFrozenList, _pipe, raise_error
+from .util import registry, SimpleFrozenList, _pipe, raise_error, _DEFAULT_EMPTY_PIPES
from .util import SimpleFrozenDict, combine_score_weights, CONFIG_SECTION_ORDER
from .util import warn_if_jupyter_cupy
from .lang.tokenizer_exceptions import URL_MATCH, BASE_EXCEPTIONS
@@ -42,8 +43,7 @@ from .lookups import load_lookups
from .compat import Literal
-if TYPE_CHECKING:
- from .pipeline import Pipe # noqa: F401
+PipeCallable = Callable[[Doc], Doc]
# This is the base config will all settings (training etc.)
@@ -180,7 +180,7 @@ class Language:
self.vocab: Vocab = vocab
if self.lang is None:
self.lang = self.vocab.lang
- self._components: List[Tuple[str, "Pipe"]] = []
+ self._components: List[Tuple[str, PipeCallable]] = []
self._disabled: Set[str] = set()
self.max_length = max_length
# Create the default tokenizer from the default config
@@ -302,7 +302,7 @@ class Language:
return SimpleFrozenList(names)
@property
- def components(self) -> List[Tuple[str, "Pipe"]]:
+ def components(self) -> List[Tuple[str, PipeCallable]]:
"""Get all (name, component) tuples in the pipeline, including the
currently disabled components.
"""
@@ -321,12 +321,12 @@ class Language:
return SimpleFrozenList(names, error=Errors.E926.format(attr="component_names"))
@property
- def pipeline(self) -> List[Tuple[str, "Pipe"]]:
+ def pipeline(self) -> List[Tuple[str, PipeCallable]]:
"""The processing pipeline consisting of (name, component) tuples. The
components are called on the Doc in order as it passes through the
pipeline.
- RETURNS (List[Tuple[str, Pipe]]): The pipeline.
+ RETURNS (List[Tuple[str, Callable[[Doc], Doc]]]): The pipeline.
"""
pipes = [(n, p) for n, p in self._components if n not in self._disabled]
return SimpleFrozenList(pipes, error=Errors.E926.format(attr="pipeline"))
@@ -465,6 +465,8 @@ class Language:
"""
if not isinstance(name, str):
raise ValueError(Errors.E963.format(decorator="factory"))
+ if "." in name:
+ raise ValueError(Errors.E853.format(name=name))
if not isinstance(default_config, dict):
err = Errors.E962.format(
style="default config", name=name, cfg_type=type(default_config)
@@ -524,7 +526,7 @@ class Language:
assigns: Iterable[str] = SimpleFrozenList(),
requires: Iterable[str] = SimpleFrozenList(),
retokenizes: bool = False,
- func: Optional["Pipe"] = None,
+ func: Optional[PipeCallable] = None,
) -> Callable[..., Any]:
"""Register a new pipeline component. Can be used for stateless function
components that don't require a separate factory. Can be used as a
@@ -539,19 +541,22 @@ class Language:
e.g. "token.ent_id". Used for pipeline analysis.
retokenizes (bool): Whether the component changes the tokenization.
Used for pipeline analysis.
- func (Optional[Callable]): Factory function if not used as a decorator.
+ func (Optional[Callable[[Doc], Doc]): Factory function if not used as a decorator.
DOCS: https://spacy.io/api/language#component
"""
- if name is not None and not isinstance(name, str):
- raise ValueError(Errors.E963.format(decorator="component"))
+ if name is not None:
+ if not isinstance(name, str):
+ raise ValueError(Errors.E963.format(decorator="component"))
+ if "." in name:
+ raise ValueError(Errors.E853.format(name=name))
component_name = name if name is not None else util.get_object_name(func)
- def add_component(component_func: "Pipe") -> Callable:
+ def add_component(component_func: PipeCallable) -> Callable:
if isinstance(func, type): # function is a class
raise ValueError(Errors.E965.format(name=component_name))
- def factory_func(nlp, name: str) -> "Pipe":
+ def factory_func(nlp, name: str) -> PipeCallable:
return component_func
internal_name = cls.get_factory_name(name)
@@ -601,7 +606,7 @@ class Language:
print_pipe_analysis(analysis, keys=keys)
return analysis
- def get_pipe(self, name: str) -> "Pipe":
+ def get_pipe(self, name: str) -> PipeCallable:
"""Get a pipeline component for a given component name.
name (str): Name of pipeline component to get.
@@ -622,7 +627,7 @@ class Language:
config: Dict[str, Any] = SimpleFrozenDict(),
raw_config: Optional[Config] = None,
validate: bool = True,
- ) -> "Pipe":
+ ) -> PipeCallable:
"""Create a pipeline component. Mostly used internally. To create and
add a component to the pipeline, you can use nlp.add_pipe.
@@ -634,7 +639,7 @@ class Language:
raw_config (Optional[Config]): Internals: the non-interpolated config.
validate (bool): Whether to validate the component config against the
arguments and types expected by the factory.
- RETURNS (Pipe): The pipeline component.
+ RETURNS (Callable[[Doc], Doc]): The pipeline component.
DOCS: https://spacy.io/api/language#create_pipe
"""
@@ -689,24 +694,18 @@ class Language:
def create_pipe_from_source(
self, source_name: str, source: "Language", *, name: str
- ) -> Tuple["Pipe", str]:
+ ) -> Tuple[PipeCallable, str]:
"""Create a pipeline component by copying it from an existing model.
source_name (str): Name of the component in the source pipeline.
source (Language): The source nlp object to copy from.
name (str): Optional alternative name to use in current pipeline.
- RETURNS (Tuple[Callable, str]): The component and its factory name.
+ RETURNS (Tuple[Callable[[Doc], Doc], str]): The component and its factory name.
"""
# Check source type
if not isinstance(source, Language):
raise ValueError(Errors.E945.format(name=source_name, source=type(source)))
- # Check vectors, with faster checks first
- if (
- self.vocab.vectors.shape != source.vocab.vectors.shape
- or self.vocab.vectors.key2row != source.vocab.vectors.key2row
- or self.vocab.vectors.to_bytes(exclude=["strings"])
- != source.vocab.vectors.to_bytes(exclude=["strings"])
- ):
+ if self.vocab.vectors != source.vocab.vectors:
warnings.warn(Warnings.W113.format(name=source_name))
if source_name not in source.component_names:
raise KeyError(
@@ -740,7 +739,7 @@ class Language:
config: Dict[str, Any] = SimpleFrozenDict(),
raw_config: Optional[Config] = None,
validate: bool = True,
- ) -> "Pipe":
+ ) -> PipeCallable:
"""Add a component to the processing pipeline. Valid components are
callables that take a `Doc` object, modify it and return it. Only one
of before/after/first/last can be set. Default behaviour is "last".
@@ -763,7 +762,7 @@ class Language:
raw_config (Optional[Config]): Internals: the non-interpolated config.
validate (bool): Whether to validate the component config against the
arguments and types expected by the factory.
- RETURNS (Pipe): The pipeline component.
+ RETURNS (Callable[[Doc], Doc]): The pipeline component.
DOCS: https://spacy.io/api/language#add_pipe
"""
@@ -774,6 +773,9 @@ class Language:
name = name if name is not None else factory_name
if name in self.component_names:
raise ValueError(Errors.E007.format(name=name, opts=self.component_names))
+ # Overriding pipe name in the config is not supported and will be ignored.
+ if "name" in config:
+ warnings.warn(Warnings.W119.format(name_in_config=config.pop("name")))
if source is not None:
# We're loading the component from a model. After loading the
# component, we know its real factory name
@@ -781,14 +783,6 @@ class Language:
factory_name, source, name=name
)
else:
- if not self.has_factory(factory_name):
- err = Errors.E002.format(
- name=factory_name,
- opts=", ".join(self.factory_names),
- method="add_pipe",
- lang=util.get_object_name(self),
- lang_code=self.lang,
- )
pipe_component = self.create_pipe(
factory_name,
name=name,
@@ -874,7 +868,7 @@ class Language:
*,
config: Dict[str, Any] = SimpleFrozenDict(),
validate: bool = True,
- ) -> "Pipe":
+ ) -> PipeCallable:
"""Replace a component in the pipeline.
name (str): Name of the component to replace.
@@ -883,7 +877,7 @@ class Language:
component. Will be merged with default config, if available.
validate (bool): Whether to validate the component config against the
arguments and types expected by the factory.
- RETURNS (Pipe): The new pipeline component.
+ RETURNS (Callable[[Doc], Doc]): The new pipeline component.
DOCS: https://spacy.io/api/language#replace_pipe
"""
@@ -935,11 +929,11 @@ class Language:
init_cfg = self._config["initialize"]["components"].pop(old_name)
self._config["initialize"]["components"][new_name] = init_cfg
- def remove_pipe(self, name: str) -> Tuple[str, "Pipe"]:
+ def remove_pipe(self, name: str) -> Tuple[str, PipeCallable]:
"""Remove a component from the pipeline.
name (str): Name of the component to remove.
- RETURNS (tuple): A `(name, component)` tuple of the removed component.
+ RETURNS (Tuple[str, Callable[[Doc], Doc]]): A `(name, component)` tuple of the removed component.
DOCS: https://spacy.io/api/language#remove_pipe
"""
@@ -1020,8 +1014,8 @@ class Language:
raise ValueError(Errors.E109.format(name=name)) from e
except Exception as e:
error_handler(name, proc, [doc], e)
- if doc is None:
- raise ValueError(Errors.E005.format(name=name))
+ if not isinstance(doc, Doc):
+ raise ValueError(Errors.E005.format(name=name, returned_type=type(doc)))
return doc
def disable_pipes(self, *names) -> "DisabledPipes":
@@ -1055,7 +1049,7 @@ class Language:
"""
if enable is None and disable is None:
raise ValueError(Errors.E991)
- if disable is not None and isinstance(disable, str):
+ if isinstance(disable, str):
disable = [disable]
if enable is not None:
if isinstance(enable, str):
@@ -1087,16 +1081,21 @@ class Language:
)
return self.tokenizer(text)
- def _ensure_doc(self, doc_like: Union[str, Doc]) -> Doc:
- """Create a Doc if need be, or raise an error if the input is not a Doc or a string."""
+ def _ensure_doc(self, doc_like: Union[str, Doc, bytes]) -> Doc:
+ """Create a Doc if need be, or raise an error if the input is not
+ a Doc, string, or a byte array (generated by Doc.to_bytes())."""
if isinstance(doc_like, Doc):
return doc_like
if isinstance(doc_like, str):
return self.make_doc(doc_like)
- raise ValueError(Errors.E866.format(type=type(doc_like)))
+ if isinstance(doc_like, bytes):
+ return Doc(self.vocab).from_bytes(doc_like)
+ raise ValueError(Errors.E1041.format(type=type(doc_like)))
- def _ensure_doc_with_context(self, doc_like: Union[str, Doc], context: Any) -> Doc:
- """Create a Doc if need be and add as_tuples context, or raise an error if the input is not a Doc or a string."""
+ def _ensure_doc_with_context(
+ self, doc_like: Union[str, Doc, bytes], context: _AnyContext
+ ) -> Doc:
+ """Call _ensure_doc to generate a Doc and set its context object."""
doc = self._ensure_doc(doc_like)
doc._context = context
return doc
@@ -1349,15 +1348,15 @@ class Language:
def set_error_handler(
self,
- error_handler: Callable[[str, "Pipe", List[Doc], Exception], NoReturn],
+ error_handler: Callable[[str, PipeCallable, List[Doc], Exception], NoReturn],
):
- """Set an error handler object for all the components in the pipeline that implement
- a set_error_handler function.
+ """Set an error handler object for all the components in the pipeline
+ that implement a set_error_handler function.
- error_handler (Callable[[str, Pipe, List[Doc], Exception], NoReturn]):
- Function that deals with a failing batch of documents. This callable function should take in
- the component's name, the component itself, the offending batch of documents, and the exception
- that was thrown.
+ error_handler (Callable[[str, Callable[[Doc], Doc], List[Doc], Exception], NoReturn]):
+ Function that deals with a failing batch of documents. This callable
+ function should take in the component's name, the component itself,
+ the offending batch of documents, and the exception that was thrown.
DOCS: https://spacy.io/api/language#set_error_handler
"""
self.default_error_handler = error_handler
@@ -1516,7 +1515,6 @@ class Language:
DOCS: https://spacy.io/api/language#pipe
"""
- # Handle texts with context as tuples
if as_tuples:
texts = cast(Iterable[Tuple[Union[str, Doc], _AnyContext]], texts)
docs_with_contexts = (
@@ -1594,8 +1592,21 @@ class Language:
n_process: int,
batch_size: int,
) -> Iterator[Doc]:
+ def prepare_input(
+ texts: Iterable[Union[str, Doc]]
+ ) -> Iterable[Tuple[Union[str, bytes], _AnyContext]]:
+ # Serialize Doc inputs to bytes to avoid incurring pickling
+ # overhead when they are passed to child processes. Also yield
+ # any context objects they might have separately (as they are not serialized).
+ for doc_like in texts:
+ if isinstance(doc_like, Doc):
+ yield (doc_like.to_bytes(), cast(_AnyContext, doc_like._context))
+ else:
+ yield (doc_like, cast(_AnyContext, None))
+
+ serialized_texts_with_ctx = prepare_input(texts) # type: ignore
# raw_texts is used later to stop iteration.
- texts, raw_texts = itertools.tee(texts)
+ texts, raw_texts = itertools.tee(serialized_texts_with_ctx) # type: ignore
# for sending texts to worker
texts_q: List[mp.Queue] = [mp.Queue() for _ in range(n_process)]
# for receiving byte-encoded docs from worker
@@ -1615,7 +1626,13 @@ class Language:
procs = [
mp.Process(
target=_apply_pipes,
- args=(self._ensure_doc, pipes, rch, sch, Underscore.get_state()),
+ args=(
+ self._ensure_doc_with_context,
+ pipes,
+ rch,
+ sch,
+ Underscore.get_state(),
+ ),
)
for rch, sch in zip(texts_q, bytedocs_send_ch)
]
@@ -1628,12 +1645,12 @@ class Language:
recv.recv() for recv in cycle(bytedocs_recv_ch)
)
try:
- for i, (_, (byte_doc, byte_context, byte_error)) in enumerate(
+ for i, (_, (byte_doc, context, byte_error)) in enumerate(
zip(raw_texts, byte_tuples), 1
):
if byte_doc is not None:
doc = Doc(self.vocab).from_bytes(byte_doc)
- doc._context = byte_context
+ doc._context = context
yield doc
elif byte_error is not None:
error = srsly.msgpack_loads(byte_error)
@@ -1667,8 +1684,9 @@ class Language:
config: Union[Dict[str, Any], Config] = {},
*,
vocab: Union[Vocab, bool] = True,
- disable: Iterable[str] = SimpleFrozenList(),
- exclude: Iterable[str] = SimpleFrozenList(),
+ disable: Union[str, Iterable[str]] = _DEFAULT_EMPTY_PIPES,
+ enable: Union[str, Iterable[str]] = _DEFAULT_EMPTY_PIPES,
+ exclude: Union[str, Iterable[str]] = _DEFAULT_EMPTY_PIPES,
meta: Dict[str, Any] = SimpleFrozenDict(),
auto_fill: bool = True,
validate: bool = True,
@@ -1679,10 +1697,12 @@ class Language:
config (Dict[str, Any] / Config): The loaded config.
vocab (Vocab): A Vocab object. If True, a vocab is created.
- disable (Iterable[str]): Names of pipeline components to disable.
+ disable (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to disable.
Disabled pipes will be loaded but they won't be run unless you
explicitly enable them by calling nlp.enable_pipe.
- exclude (Iterable[str]): Names of pipeline components to exclude.
+ enable (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to enable. All other
+ pipes will be disabled (and can be enabled using `nlp.enable_pipe`).
+ exclude (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to exclude.
Excluded components won't be loaded.
meta (Dict[str, Any]): Meta overrides for nlp.meta.
auto_fill (bool): Automatically fill in missing values in config based
@@ -1835,8 +1855,35 @@ class Language:
# Restore the original vocab after sourcing if necessary
if vocab_b is not None:
nlp.vocab.from_bytes(vocab_b)
- disabled_pipes = [*config["nlp"]["disabled"], *disable]
+
+ # Resolve disabled/enabled settings.
+ if isinstance(disable, str):
+ disable = [disable]
+ if isinstance(enable, str):
+ enable = [enable]
+ if isinstance(exclude, str):
+ exclude = [exclude]
+
+ # `enable` should not be merged with `enabled` (the opposite is true for `disable`/`disabled`). If the config
+ # specifies values for `enabled` not included in `enable`, emit warning.
+ if id(enable) != id(_DEFAULT_EMPTY_PIPES):
+ enabled = config["nlp"].get("enabled", [])
+ if len(enabled) and not set(enabled).issubset(enable):
+ warnings.warn(
+ Warnings.W123.format(
+ enable=enable,
+ enabled=enabled,
+ )
+ )
+
+ # Ensure sets of disabled/enabled pipe names are not contradictory.
+ disabled_pipes = cls._resolve_component_status(
+ list({*disable, *config["nlp"].get("disabled", [])}),
+ enable,
+ config["nlp"]["pipeline"],
+ )
nlp._disabled = set(p for p in disabled_pipes if p not in exclude)
+
nlp.batch_size = config["nlp"]["batch_size"]
nlp.config = filled if auto_fill else config
if after_pipeline_creation is not None:
@@ -1988,6 +2035,41 @@ class Language:
serializers["vocab"] = lambda p: self.vocab.to_disk(p, exclude=exclude)
util.to_disk(path, serializers, exclude)
+ @staticmethod
+ def _resolve_component_status(
+ disable: Union[str, Iterable[str]],
+ enable: Union[str, Iterable[str]],
+ pipe_names: Iterable[str],
+ ) -> Tuple[str, ...]:
+ """Derives whether (1) `disable` and `enable` values are consistent and (2)
+ resolves those to a single set of disabled components. Raises an error in
+ case of inconsistency.
+
+ disable (Union[str, Iterable[str]]): Name(s) of component(s) or serialization fields to disable.
+ enable (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to enable.
+ pipe_names (Iterable[str]): Names of all pipeline components.
+
+ RETURNS (Tuple[str, ...]): Names of components to exclude from pipeline w.r.t.
+ specified includes and excludes.
+ """
+
+ if isinstance(disable, str):
+ disable = [disable]
+ to_disable = disable
+
+ if enable:
+ if isinstance(enable, str):
+ enable = [enable]
+ to_disable = {
+ *[pipe_name for pipe_name in pipe_names if pipe_name not in enable],
+ *disable,
+ }
+ # If any pipe to be enabled is in to_disable, the specification is inconsistent.
+ if len(set(enable) & to_disable):
+ raise ValueError(Errors.E1042.format(enable=enable, disable=disable))
+
+ return tuple(to_disable)
+
def from_disk(
self,
path: Union[str, Path],
@@ -2160,7 +2242,7 @@ def _copy_examples(examples: Iterable[Example]) -> List[Example]:
def _apply_pipes(
- ensure_doc: Callable[[Union[str, Doc]], Doc],
+ ensure_doc: Callable[[Union[str, Doc, bytes], _AnyContext], Doc],
pipes: Iterable[Callable[..., Iterator[Doc]]],
receiver,
sender,
@@ -2181,17 +2263,19 @@ def _apply_pipes(
Underscore.load_state(underscore_state)
while True:
try:
- texts = receiver.get()
- docs = (ensure_doc(text) for text in texts)
+ texts_with_ctx = receiver.get()
+ docs = (
+ ensure_doc(doc_like, context) for doc_like, context in texts_with_ctx
+ )
for pipe in pipes:
docs = pipe(docs) # type: ignore[arg-type, assignment]
# Connection does not accept unpickable objects, so send list.
byte_docs = [(doc.to_bytes(), doc._context, None) for doc in docs]
- padding = [(None, None, None)] * (len(texts) - len(byte_docs))
+ padding = [(None, None, None)] * (len(texts_with_ctx) - len(byte_docs))
sender.send(byte_docs + padding) # type: ignore[operator]
except Exception:
error_msg = [(None, None, srsly.msgpack_dumps(traceback.format_exc()))]
- padding = [(None, None, None)] * (len(texts) - 1)
+ padding = [(None, None, None)] * (len(texts_with_ctx) - 1)
sender.send(error_msg + padding)
diff --git a/spacy/lookups.py b/spacy/lookups.py
index b2f3dc15e..d7cc44fb3 100644
--- a/spacy/lookups.py
+++ b/spacy/lookups.py
@@ -85,7 +85,7 @@ class Table(OrderedDict):
value: The value to set.
"""
key = get_string_id(key)
- OrderedDict.__setitem__(self, key, value)
+ OrderedDict.__setitem__(self, key, value) # type:ignore[assignment]
self.bloom.add(key)
def set(self, key: Union[str, int], value: Any) -> None:
@@ -104,7 +104,7 @@ class Table(OrderedDict):
RETURNS: The value.
"""
key = get_string_id(key)
- return OrderedDict.__getitem__(self, key)
+ return OrderedDict.__getitem__(self, key) # type:ignore[index]
def get(self, key: Union[str, int], default: Optional[Any] = None) -> Any:
"""Get the value for a given key. String keys will be hashed.
@@ -114,7 +114,7 @@ class Table(OrderedDict):
RETURNS: The value.
"""
key = get_string_id(key)
- return OrderedDict.get(self, key, default)
+ return OrderedDict.get(self, key, default) # type:ignore[arg-type]
def __contains__(self, key: Union[str, int]) -> bool: # type: ignore[override]
"""Check whether a key is in the table. String keys will be hashed.
diff --git a/spacy/matcher/__init__.py b/spacy/matcher/__init__.py
index 286844787..a4f164847 100644
--- a/spacy/matcher/__init__.py
+++ b/spacy/matcher/__init__.py
@@ -1,5 +1,6 @@
from .matcher import Matcher
from .phrasematcher import PhraseMatcher
from .dependencymatcher import DependencyMatcher
+from .levenshtein import levenshtein
-__all__ = ["Matcher", "PhraseMatcher", "DependencyMatcher"]
+__all__ = ["Matcher", "PhraseMatcher", "DependencyMatcher", "levenshtein"]
diff --git a/spacy/matcher/dependencymatcher.pyx b/spacy/matcher/dependencymatcher.pyx
index a602ba737..74c2d002f 100644
--- a/spacy/matcher/dependencymatcher.pyx
+++ b/spacy/matcher/dependencymatcher.pyx
@@ -82,6 +82,10 @@ cdef class DependencyMatcher:
"$-": self._imm_left_sib,
"$++": self._right_sib,
"$--": self._left_sib,
+ ">++": self._right_child,
+ ">--": self._left_child,
+ "<++": self._right_parent,
+ "<--": self._left_parent,
}
def __reduce__(self):
@@ -423,6 +427,22 @@ cdef class DependencyMatcher:
def _left_sib(self, doc, node):
return [doc[child.i] for child in doc[node].head.children if child.i < node]
+ def _right_child(self, doc, node):
+ return [doc[child.i] for child in doc[node].children if child.i > node]
+
+ def _left_child(self, doc, node):
+ return [doc[child.i] for child in doc[node].children if child.i < node]
+
+ def _right_parent(self, doc, node):
+ if doc[node].head.i > node:
+ return [doc[node].head]
+ return []
+
+ def _left_parent(self, doc, node):
+ if doc[node].head.i < node:
+ return [doc[node].head]
+ return []
+
def _normalize_key(self, key):
if isinstance(key, str):
return self.vocab.strings.add(key)
diff --git a/spacy/matcher/levenshtein.pyx b/spacy/matcher/levenshtein.pyx
new file mode 100644
index 000000000..e823ce99d
--- /dev/null
+++ b/spacy/matcher/levenshtein.pyx
@@ -0,0 +1,32 @@
+# cython: profile=True, binding=True, infer_types=True
+from cpython.object cimport PyObject
+from libc.stdint cimport int64_t
+
+from typing import Optional
+
+from ..util import registry
+
+
+cdef extern from "polyleven.c":
+ int64_t polyleven(PyObject *o1, PyObject *o2, int64_t k)
+
+
+cpdef int64_t levenshtein(a: str, b: str, k: Optional[int] = None):
+ if k is None:
+ k = -1
+ return polyleven(a, b, k)
+
+
+cpdef bint levenshtein_compare(input_text: str, pattern_text: str, fuzzy: int = -1):
+ if fuzzy >= 0:
+ max_edits = fuzzy
+ else:
+ # allow at least two edits (to allow at least one transposition) and up
+ # to 30% of the pattern string length
+ max_edits = max(2, round(0.3 * len(pattern_text)))
+ return levenshtein(input_text, pattern_text, max_edits) <= max_edits
+
+
+@registry.misc("spacy.levenshtein_compare.v1")
+def make_levenshtein_compare():
+ return levenshtein_compare
diff --git a/spacy/matcher/matcher.pxd b/spacy/matcher/matcher.pxd
index 455f978cc..51854d562 100644
--- a/spacy/matcher/matcher.pxd
+++ b/spacy/matcher/matcher.pxd
@@ -77,3 +77,4 @@ cdef class Matcher:
cdef public object _extensions
cdef public object _extra_predicates
cdef public object _seen_attrs
+ cdef public object _fuzzy_compare
diff --git a/spacy/matcher/matcher.pyi b/spacy/matcher/matcher.pyi
index 390629ff8..48922865b 100644
--- a/spacy/matcher/matcher.pyi
+++ b/spacy/matcher/matcher.pyi
@@ -5,7 +5,12 @@ from ..vocab import Vocab
from ..tokens import Doc, Span
class Matcher:
- def __init__(self, vocab: Vocab, validate: bool = ...) -> None: ...
+ def __init__(
+ self,
+ vocab: Vocab,
+ validate: bool = ...,
+ fuzzy_compare: Callable[[str, str, int], bool] = ...,
+ ) -> None: ...
def __reduce__(self) -> Any: ...
def __len__(self) -> int: ...
def __contains__(self, key: str) -> bool: ...
diff --git a/spacy/matcher/matcher.pyx b/spacy/matcher/matcher.pyx
index 6aa58f0e3..ea1b4b66b 100644
--- a/spacy/matcher/matcher.pyx
+++ b/spacy/matcher/matcher.pyx
@@ -1,5 +1,5 @@
-# cython: infer_types=True, cython: profile=True
-from typing import List
+# cython: binding=True, infer_types=True, profile=True
+from typing import List, Iterable
from libcpp.vector cimport vector
from libc.stdint cimport int32_t, int8_t
@@ -20,10 +20,12 @@ from ..tokens.token cimport Token
from ..tokens.morphanalysis cimport MorphAnalysis
from ..attrs cimport ID, attr_id_t, NULL_ATTR, ORTH, POS, TAG, DEP, LEMMA, MORPH, ENT_IOB
+from .levenshtein import levenshtein_compare
from ..schemas import validate_token_pattern
from ..errors import Errors, MatchPatternError, Warnings
from ..strings import get_string_id
from ..attrs import IDS
+from ..util import registry
DEF PADDING = 5
@@ -36,11 +38,13 @@ cdef class Matcher:
USAGE: https://spacy.io/usage/rule-based-matching
"""
- def __init__(self, vocab, validate=True):
+ def __init__(self, vocab, validate=True, *, fuzzy_compare=levenshtein_compare):
"""Create the Matcher.
vocab (Vocab): The vocabulary object, which must be shared with the
- documents the matcher will operate on.
+ validate (bool): Validate all patterns added to this matcher.
+ fuzzy_compare (Callable[[str, str, int], bool]): The comparison method
+ for the FUZZY operators.
"""
self._extra_predicates = []
self._patterns = {}
@@ -51,9 +55,10 @@ cdef class Matcher:
self.vocab = vocab
self.mem = Pool()
self.validate = validate
+ self._fuzzy_compare = fuzzy_compare
def __reduce__(self):
- data = (self.vocab, self._patterns, self._callbacks)
+ data = (self.vocab, self._patterns, self._callbacks, self.validate, self._fuzzy_compare)
return (unpickle_matcher, data, None, None)
def __len__(self):
@@ -86,10 +91,14 @@ cdef class Matcher:
is a dictionary mapping attribute IDs to values, and optionally a
quantifier operator under the key "op". The available quantifiers are:
- '!': Negate the pattern, by requiring it to match exactly 0 times.
- '?': Make the pattern optional, by allowing it to match 0 or 1 times.
- '+': Require the pattern to match 1 or more times.
- '*': Allow the pattern to zero or more times.
+ '!': Negate the pattern, by requiring it to match exactly 0 times.
+ '?': Make the pattern optional, by allowing it to match 0 or 1 times.
+ '+': Require the pattern to match 1 or more times.
+ '*': Allow the pattern to zero or more times.
+ '{n}': Require the pattern to match exactly _n_ times.
+ '{n,m}': Require the pattern to match at least _n_ but not more than _m_ times.
+ '{n,}': Require the pattern to match at least _n_ times.
+ '{,m}': Require the pattern to match at most _m_ times.
The + and * operators return all possible matches (not just the greedy
ones). However, the "greedy" argument can filter the final matches
@@ -124,7 +133,7 @@ cdef class Matcher:
for pattern in patterns:
try:
specs = _preprocess_pattern(pattern, self.vocab,
- self._extensions, self._extra_predicates)
+ self._extensions, self._extra_predicates, self._fuzzy_compare)
self.patterns.push_back(init_pattern(self.mem, key, specs))
for spec in specs:
for attr, _ in spec[1]:
@@ -244,8 +253,12 @@ cdef class Matcher:
pipe = "parser"
error_msg = Errors.E155.format(pipe=pipe, attr=self.vocab.strings.as_string(attr))
raise ValueError(error_msg)
- matches = find_matches(&self.patterns[0], self.patterns.size(), doclike, length,
- extensions=self._extensions, predicates=self._extra_predicates, with_alignments=with_alignments)
+
+ if self.patterns.empty():
+ matches = []
+ else:
+ matches = find_matches(&self.patterns[0], self.patterns.size(), doclike, length,
+ extensions=self._extensions, predicates=self._extra_predicates, with_alignments=with_alignments)
final_matches = []
pairs_by_id = {}
# For each key, either add all matches, or only the filtered,
@@ -318,8 +331,8 @@ cdef class Matcher:
return key
-def unpickle_matcher(vocab, patterns, callbacks):
- matcher = Matcher(vocab)
+def unpickle_matcher(vocab, patterns, callbacks, validate, fuzzy_compare):
+ matcher = Matcher(vocab, validate=validate, fuzzy_compare=fuzzy_compare)
for key, pattern in patterns.items():
callback = callbacks.get(key, None)
matcher.add(key, pattern, on_match=callback)
@@ -686,18 +699,14 @@ cdef int8_t get_is_match(PatternStateC state,
return True
-cdef int8_t get_is_final(PatternStateC state) nogil:
+cdef inline int8_t get_is_final(PatternStateC state) nogil:
if state.pattern[1].quantifier == FINAL_ID:
- id_attr = state.pattern[1].attrs[0]
- if id_attr.attr != ID:
- with gil:
- raise ValueError(Errors.E074.format(attr=ID, bad_attr=id_attr.attr))
return 1
else:
return 0
-cdef int8_t get_quantifier(PatternStateC state) nogil:
+cdef inline int8_t get_quantifier(PatternStateC state) nogil:
return state.pattern.quantifier
@@ -750,7 +759,7 @@ cdef attr_t get_ent_id(const TokenPatternC* pattern) nogil:
return id_attr.value
-def _preprocess_pattern(token_specs, vocab, extensions_table, extra_predicates):
+def _preprocess_pattern(token_specs, vocab, extensions_table, extra_predicates, fuzzy_compare):
"""This function interprets the pattern, converting the various bits of
syntactic sugar before we compile it into a struct with init_pattern.
@@ -777,7 +786,7 @@ def _preprocess_pattern(token_specs, vocab, extensions_table, extra_predicates):
ops = _get_operators(spec)
attr_values = _get_attr_values(spec, string_store)
extensions = _get_extensions(spec, string_store, extensions_table)
- predicates = _get_extra_predicates(spec, extra_predicates, vocab)
+ predicates = _get_extra_predicates(spec, extra_predicates, vocab, fuzzy_compare)
for op in ops:
tokens.append((op, list(attr_values), list(extensions), list(predicates), token_idx))
return tokens
@@ -786,6 +795,7 @@ def _preprocess_pattern(token_specs, vocab, extensions_table, extra_predicates):
def _get_attr_values(spec, string_store):
attr_values = []
for attr, value in spec.items():
+ input_attr = attr
if isinstance(attr, str):
attr = attr.upper()
if attr == '_':
@@ -814,23 +824,52 @@ def _get_attr_values(spec, string_store):
attr_values.append((attr, value))
else:
# should be caught in validation
- raise ValueError(Errors.E152.format(attr=attr))
+ raise ValueError(Errors.E152.format(attr=input_attr))
return attr_values
# These predicate helper classes are used to match the REGEX, IN, >= etc
# extensions to the matcher introduced in #3173.
+class _FuzzyPredicate:
+ operators = ("FUZZY", "FUZZY1", "FUZZY2", "FUZZY3", "FUZZY4", "FUZZY5",
+ "FUZZY6", "FUZZY7", "FUZZY8", "FUZZY9")
+
+ def __init__(self, i, attr, value, predicate, is_extension=False, vocab=None,
+ regex=False, fuzzy=None, fuzzy_compare=None):
+ self.i = i
+ self.attr = attr
+ self.value = value
+ self.predicate = predicate
+ self.is_extension = is_extension
+ if self.predicate not in self.operators:
+ raise ValueError(Errors.E126.format(good=self.operators, bad=self.predicate))
+ fuzz = self.predicate[len("FUZZY"):] # number after prefix
+ self.fuzzy = int(fuzz) if fuzz else -1
+ self.fuzzy_compare = fuzzy_compare
+ self.key = (self.attr, self.fuzzy, self.predicate, srsly.json_dumps(value, sort_keys=True))
+
+ def __call__(self, Token token):
+ if self.is_extension:
+ value = token._.get(self.attr)
+ else:
+ value = token.vocab.strings[get_token_attr_for_matcher(token.c, self.attr)]
+ if self.value == value:
+ return True
+ return self.fuzzy_compare(value, self.value, self.fuzzy)
+
+
class _RegexPredicate:
operators = ("REGEX",)
- def __init__(self, i, attr, value, predicate, is_extension=False, vocab=None):
+ def __init__(self, i, attr, value, predicate, is_extension=False, vocab=None,
+ regex=False, fuzzy=None, fuzzy_compare=None):
self.i = i
self.attr = attr
self.value = re.compile(value)
self.predicate = predicate
self.is_extension = is_extension
- self.key = (attr, self.predicate, srsly.json_dumps(value, sort_keys=True))
+ self.key = (self.attr, self.predicate, srsly.json_dumps(value, sort_keys=True))
if self.predicate not in self.operators:
raise ValueError(Errors.E126.format(good=self.operators, bad=self.predicate))
@@ -845,41 +884,78 @@ class _RegexPredicate:
class _SetPredicate:
operators = ("IN", "NOT_IN", "IS_SUBSET", "IS_SUPERSET", "INTERSECTS")
- def __init__(self, i, attr, value, predicate, is_extension=False, vocab=None):
+ def __init__(self, i, attr, value, predicate, is_extension=False, vocab=None,
+ regex=False, fuzzy=None, fuzzy_compare=None):
self.i = i
self.attr = attr
self.vocab = vocab
+ self.regex = regex
+ self.fuzzy = fuzzy
+ self.fuzzy_compare = fuzzy_compare
if self.attr == MORPH:
# normalize morph strings
self.value = set(self.vocab.morphology.add(v) for v in value)
else:
- self.value = set(get_string_id(v) for v in value)
+ if self.regex:
+ self.value = set(re.compile(v) for v in value)
+ elif self.fuzzy is not None:
+ # add to string store
+ self.value = set(self.vocab.strings.add(v) for v in value)
+ else:
+ self.value = set(get_string_id(v) for v in value)
self.predicate = predicate
self.is_extension = is_extension
- self.key = (attr, self.predicate, srsly.json_dumps(value, sort_keys=True))
+ self.key = (self.attr, self.regex, self.fuzzy, self.predicate, srsly.json_dumps(value, sort_keys=True))
if self.predicate not in self.operators:
raise ValueError(Errors.E126.format(good=self.operators, bad=self.predicate))
def __call__(self, Token token):
if self.is_extension:
- value = get_string_id(token._.get(self.attr))
+ value = token._.get(self.attr)
else:
value = get_token_attr_for_matcher(token.c, self.attr)
- if self.predicate in ("IS_SUBSET", "IS_SUPERSET", "INTERSECTS"):
+ if self.predicate in ("IN", "NOT_IN"):
+ if isinstance(value, (str, int)):
+ value = get_string_id(value)
+ else:
+ return False
+ elif self.predicate in ("IS_SUBSET", "IS_SUPERSET", "INTERSECTS"):
+ # ensure that all values are enclosed in a set
if self.attr == MORPH:
# break up MORPH into individual Feat=Val values
value = set(get_string_id(v) for v in MorphAnalysis.from_id(self.vocab, value))
+ elif isinstance(value, (str, int)):
+ value = set((get_string_id(value),))
+ elif isinstance(value, Iterable) and all(isinstance(v, (str, int)) for v in value):
+ value = set(get_string_id(v) for v in value)
else:
- # treat a single value as a list
- if isinstance(value, (str, int)):
- value = set([get_string_id(value)])
- else:
- value = set(get_string_id(v) for v in value)
+ return False
+
if self.predicate == "IN":
- return value in self.value
+ if self.regex:
+ value = self.vocab.strings[value]
+ return any(bool(v.search(value)) for v in self.value)
+ elif self.fuzzy is not None:
+ value = self.vocab.strings[value]
+ return any(self.fuzzy_compare(value, self.vocab.strings[v], self.fuzzy)
+ for v in self.value)
+ elif value in self.value:
+ return True
+ else:
+ return False
elif self.predicate == "NOT_IN":
- return value not in self.value
+ if self.regex:
+ value = self.vocab.strings[value]
+ return not any(bool(v.search(value)) for v in self.value)
+ elif self.fuzzy is not None:
+ value = self.vocab.strings[value]
+ return not any(self.fuzzy_compare(value, self.vocab.strings[v], self.fuzzy)
+ for v in self.value)
+ elif value in self.value:
+ return False
+ else:
+ return True
elif self.predicate == "IS_SUBSET":
return value <= self.value
elif self.predicate == "IS_SUPERSET":
@@ -894,13 +970,14 @@ class _SetPredicate:
class _ComparisonPredicate:
operators = ("==", "!=", ">=", "<=", ">", "<")
- def __init__(self, i, attr, value, predicate, is_extension=False, vocab=None):
+ def __init__(self, i, attr, value, predicate, is_extension=False, vocab=None,
+ regex=False, fuzzy=None, fuzzy_compare=None):
self.i = i
self.attr = attr
self.value = value
self.predicate = predicate
self.is_extension = is_extension
- self.key = (attr, self.predicate, srsly.json_dumps(value, sort_keys=True))
+ self.key = (self.attr, self.predicate, srsly.json_dumps(value, sort_keys=True))
if self.predicate not in self.operators:
raise ValueError(Errors.E126.format(good=self.operators, bad=self.predicate))
@@ -923,7 +1000,7 @@ class _ComparisonPredicate:
return value < self.value
-def _get_extra_predicates(spec, extra_predicates, vocab):
+def _get_extra_predicates(spec, extra_predicates, vocab, fuzzy_compare):
predicate_types = {
"REGEX": _RegexPredicate,
"IN": _SetPredicate,
@@ -937,6 +1014,16 @@ def _get_extra_predicates(spec, extra_predicates, vocab):
"<=": _ComparisonPredicate,
">": _ComparisonPredicate,
"<": _ComparisonPredicate,
+ "FUZZY": _FuzzyPredicate,
+ "FUZZY1": _FuzzyPredicate,
+ "FUZZY2": _FuzzyPredicate,
+ "FUZZY3": _FuzzyPredicate,
+ "FUZZY4": _FuzzyPredicate,
+ "FUZZY5": _FuzzyPredicate,
+ "FUZZY6": _FuzzyPredicate,
+ "FUZZY7": _FuzzyPredicate,
+ "FUZZY8": _FuzzyPredicate,
+ "FUZZY9": _FuzzyPredicate,
}
seen_predicates = {pred.key: pred.i for pred in extra_predicates}
output = []
@@ -954,22 +1041,47 @@ def _get_extra_predicates(spec, extra_predicates, vocab):
attr = "ORTH"
attr = IDS.get(attr.upper())
if isinstance(value, dict):
- processed = False
- value_with_upper_keys = {k.upper(): v for k, v in value.items()}
- for type_, cls in predicate_types.items():
- if type_ in value_with_upper_keys:
- predicate = cls(len(extra_predicates), attr, value_with_upper_keys[type_], type_, vocab=vocab)
- # Don't create a redundant predicates.
- # This helps with efficiency, as we're caching the results.
- if predicate.key in seen_predicates:
- output.append(seen_predicates[predicate.key])
- else:
- extra_predicates.append(predicate)
- output.append(predicate.i)
- seen_predicates[predicate.key] = predicate.i
- processed = True
- if not processed:
- warnings.warn(Warnings.W035.format(pattern=value))
+ output.extend(_get_extra_predicates_dict(attr, value, vocab, predicate_types,
+ extra_predicates, seen_predicates, fuzzy_compare=fuzzy_compare))
+ return output
+
+
+def _get_extra_predicates_dict(attr, value_dict, vocab, predicate_types,
+ extra_predicates, seen_predicates, regex=False, fuzzy=None, fuzzy_compare=None):
+ output = []
+ for type_, value in value_dict.items():
+ type_ = type_.upper()
+ cls = predicate_types.get(type_)
+ if cls is None:
+ warnings.warn(Warnings.W035.format(pattern=value_dict))
+ # ignore unrecognized predicate type
+ continue
+ elif cls == _RegexPredicate:
+ if isinstance(value, dict):
+ # add predicates inside regex operator
+ output.extend(_get_extra_predicates_dict(attr, value, vocab, predicate_types,
+ extra_predicates, seen_predicates,
+ regex=True))
+ continue
+ elif cls == _FuzzyPredicate:
+ if isinstance(value, dict):
+ # add predicates inside fuzzy operator
+ fuzz = type_[len("FUZZY"):] # number after prefix
+ fuzzy_val = int(fuzz) if fuzz else -1
+ output.extend(_get_extra_predicates_dict(attr, value, vocab, predicate_types,
+ extra_predicates, seen_predicates,
+ fuzzy=fuzzy_val, fuzzy_compare=fuzzy_compare))
+ continue
+ predicate = cls(len(extra_predicates), attr, value, type_, vocab=vocab,
+ regex=regex, fuzzy=fuzzy, fuzzy_compare=fuzzy_compare)
+ # Don't create redundant predicates.
+ # This helps with efficiency, as we're caching the results.
+ if predicate.key in seen_predicates:
+ output.append(seen_predicates[predicate.key])
+ else:
+ extra_predicates.append(predicate)
+ output.append(predicate.i)
+ seen_predicates[predicate.key] = predicate.i
return output
@@ -1003,8 +1115,29 @@ def _get_operators(spec):
return (ONE,)
elif spec["OP"] in lookup:
return lookup[spec["OP"]]
+ #Min_max {n,m}
+ elif spec["OP"].startswith("{") and spec["OP"].endswith("}"):
+ # {n} --> {n,n} exactly n ONE,(n)
+ # {n,m}--> {n,m} min of n, max of m ONE,(n),ZERO_ONE,(m)
+ # {,m} --> {0,m} min of zero, max of m ZERO_ONE,(m)
+ # {n,} --> {n,∞} min of n, max of inf ONE,(n),ZERO_PLUS
+
+ min_max = spec["OP"][1:-1]
+ min_max = min_max if "," in min_max else f"{min_max},{min_max}"
+ n, m = min_max.split(",")
+
+ #1. Either n or m is a blank string and the other is numeric -->isdigit
+ #2. Both are numeric and n <= m
+ if (not n.isdecimal() and not m.isdecimal()) or (n.isdecimal() and m.isdecimal() and int(n) > int(m)):
+ keys = ", ".join(lookup.keys()) + ", {n}, {n,m}, {n,}, {,m} where n and m are integers and n <= m "
+ raise ValueError(Errors.E011.format(op=spec["OP"], opts=keys))
+
+ # if n is empty string, zero would be used
+ head = tuple(ONE for __ in range(int(n or 0)))
+ tail = tuple(ZERO_ONE for __ in range(int(m) - int(n or 0))) if m else (ZERO_PLUS,)
+ return head + tail
else:
- keys = ", ".join(lookup.keys())
+ keys = ", ".join(lookup.keys()) + ", {n}, {n,m}, {n,}, {,m} where n and m are integers and n <= m "
raise ValueError(Errors.E011.format(op=spec["OP"], opts=keys))
diff --git a/spacy/matcher/phrasematcher.pyx b/spacy/matcher/phrasematcher.pyx
index 2ff5105ad..382029872 100644
--- a/spacy/matcher/phrasematcher.pyx
+++ b/spacy/matcher/phrasematcher.pyx
@@ -118,6 +118,8 @@ cdef class PhraseMatcher:
# if token is not found, break out of the loop
current_node = NULL
break
+ path_nodes.push_back(current_node)
+ path_keys.push_back(self._terminal_hash)
# remove the tokens from trie node if there are no other
# keywords with them
result = map_get(current_node, self._terminal_hash)
diff --git a/spacy/matcher/polyleven.c b/spacy/matcher/polyleven.c
new file mode 100644
index 000000000..2f2b8826c
--- /dev/null
+++ b/spacy/matcher/polyleven.c
@@ -0,0 +1,384 @@
+/*
+ * Adapted from Polyleven (https://ceptord.net/)
+ *
+ * Source: https://github.com/fujimotos/polyleven/blob/c3f95a080626c5652f0151a2e449963288ccae84/polyleven.c
+ *
+ * Copyright (c) 2021 Fujimoto Seiji
+ * Copyright (c) 2021 Max Bachmann
+ * Copyright (c) 2022 Nick Mazuk
+ * Copyright (c) 2022 Michael Weiss
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+#include
+#include
+
+#define MIN(a,b) ((a) < (b) ? (a) : (b))
+#define MAX(a,b) ((a) > (b) ? (a) : (b))
+#define CDIV(a,b) ((a) / (b) + ((a) % (b) > 0))
+#define BIT(i,n) (((i) >> (n)) & 1)
+#define FLIP(i,n) ((i) ^ ((uint64_t) 1 << (n)))
+#define ISASCII(kd) ((kd) == PyUnicode_1BYTE_KIND)
+
+/*
+ * Bare bone of PyUnicode
+ */
+struct strbuf {
+ void *ptr;
+ int kind;
+ int64_t len;
+};
+
+static void strbuf_init(struct strbuf *s, PyObject *o)
+{
+ s->ptr = PyUnicode_DATA(o);
+ s->kind = PyUnicode_KIND(o);
+ s->len = PyUnicode_GET_LENGTH(o);
+}
+
+#define strbuf_read(s, i) PyUnicode_READ((s)->kind, (s)->ptr, (i))
+
+/*
+ * An encoded mbleven model table.
+ *
+ * Each 8-bit integer represents an edit sequence, with using two
+ * bits for a single operation.
+ *
+ * 01 = DELETE, 10 = INSERT, 11 = REPLACE
+ *
+ * For example, 13 is '1101' in binary notation, so it means
+ * DELETE + REPLACE.
+ */
+static const uint8_t MBLEVEN_MATRIX[] = {
+ 3, 0, 0, 0, 0, 0, 0, 0,
+ 1, 0, 0, 0, 0, 0, 0, 0,
+ 15, 9, 6, 0, 0, 0, 0, 0,
+ 13, 7, 0, 0, 0, 0, 0, 0,
+ 5, 0, 0, 0, 0, 0, 0, 0,
+ 63, 39, 45, 57, 54, 30, 27, 0,
+ 61, 55, 31, 37, 25, 22, 0, 0,
+ 53, 29, 23, 0, 0, 0, 0, 0,
+ 21, 0, 0, 0, 0, 0, 0, 0,
+};
+
+#define MBLEVEN_MATRIX_GET(k, d) ((((k) + (k) * (k)) / 2 - 1) + (d)) * 8
+
+static int64_t mbleven_ascii(char *s1, int64_t len1,
+ char *s2, int64_t len2, int k)
+{
+ int pos;
+ uint8_t m;
+ int64_t i, j, c, r;
+
+ pos = MBLEVEN_MATRIX_GET(k, len1 - len2);
+ r = k + 1;
+
+ while (MBLEVEN_MATRIX[pos]) {
+ m = MBLEVEN_MATRIX[pos++];
+ i = j = c = 0;
+ while (i < len1 && j < len2) {
+ if (s1[i] != s2[j]) {
+ c++;
+ if (!m) break;
+ if (m & 1) i++;
+ if (m & 2) j++;
+ m >>= 2;
+ } else {
+ i++;
+ j++;
+ }
+ }
+ c += (len1 - i) + (len2 - j);
+ r = MIN(r, c);
+ if (r < 2) {
+ return r;
+ }
+ }
+ return r;
+}
+
+static int64_t mbleven(PyObject *o1, PyObject *o2, int64_t k)
+{
+ int pos;
+ uint8_t m;
+ int64_t i, j, c, r;
+ struct strbuf s1, s2;
+
+ strbuf_init(&s1, o1);
+ strbuf_init(&s2, o2);
+
+ if (s1.len < s2.len)
+ return mbleven(o2, o1, k);
+
+ if (k > 3)
+ return -1;
+
+ if (k < s1.len - s2.len)
+ return k + 1;
+
+ if (ISASCII(s1.kind) && ISASCII(s2.kind))
+ return mbleven_ascii(s1.ptr, s1.len, s2.ptr, s2.len, k);
+
+ pos = MBLEVEN_MATRIX_GET(k, s1.len - s2.len);
+ r = k + 1;
+
+ while (MBLEVEN_MATRIX[pos]) {
+ m = MBLEVEN_MATRIX[pos++];
+ i = j = c = 0;
+ while (i < s1.len && j < s2.len) {
+ if (strbuf_read(&s1, i) != strbuf_read(&s2, j)) {
+ c++;
+ if (!m) break;
+ if (m & 1) i++;
+ if (m & 2) j++;
+ m >>= 2;
+ } else {
+ i++;
+ j++;
+ }
+ }
+ c += (s1.len - i) + (s2.len - j);
+ r = MIN(r, c);
+ if (r < 2) {
+ return r;
+ }
+ }
+ return r;
+}
+
+/*
+ * Data structure to store Peq (equality bit-vector).
+ */
+struct blockmap_entry {
+ uint32_t key[128];
+ uint64_t val[128];
+};
+
+struct blockmap {
+ int64_t nr;
+ struct blockmap_entry *list;
+};
+
+#define blockmap_key(c) ((c) | 0x80000000U)
+#define blockmap_hash(c) ((c) % 128)
+
+static int blockmap_init(struct blockmap *map, struct strbuf *s)
+{
+ int64_t i;
+ struct blockmap_entry *be;
+ uint32_t c, k;
+ uint8_t h;
+
+ map->nr = CDIV(s->len, 64);
+ map->list = calloc(1, map->nr * sizeof(struct blockmap_entry));
+ if (map->list == NULL) {
+ PyErr_NoMemory();
+ return -1;
+ }
+
+ for (i = 0; i < s->len; i++) {
+ be = &(map->list[i / 64]);
+ c = strbuf_read(s, i);
+ h = blockmap_hash(c);
+ k = blockmap_key(c);
+
+ while (be->key[h] && be->key[h] != k)
+ h = blockmap_hash(h + 1);
+ be->key[h] = k;
+ be->val[h] |= (uint64_t) 1 << (i % 64);
+ }
+ return 0;
+}
+
+static void blockmap_clear(struct blockmap *map)
+{
+ if (map->list)
+ free(map->list);
+ map->list = NULL;
+ map->nr = 0;
+}
+
+static uint64_t blockmap_get(struct blockmap *map, int block, uint32_t c)
+{
+ struct blockmap_entry *be;
+ uint8_t h;
+ uint32_t k;
+
+ h = blockmap_hash(c);
+ k = blockmap_key(c);
+
+ be = &(map->list[block]);
+ while (be->key[h] && be->key[h] != k)
+ h = blockmap_hash(h + 1);
+ return be->key[h] == k ? be->val[h] : 0;
+}
+
+/*
+ * Myers' bit-parallel algorithm
+ *
+ * See: G. Myers. "A fast bit-vector algorithm for approximate string
+ * matching based on dynamic programming." Journal of the ACM, 1999.
+ */
+static int64_t myers1999_block(struct strbuf *s1, struct strbuf *s2,
+ struct blockmap *map)
+{
+ uint64_t Eq, Xv, Xh, Ph, Mh, Pv, Mv, Last;
+ uint64_t *Mhc, *Phc;
+ int64_t i, b, hsize, vsize, Score;
+ uint8_t Pb, Mb;
+
+ hsize = CDIV(s1->len, 64);
+ vsize = CDIV(s2->len, 64);
+ Score = s2->len;
+
+ Phc = malloc(hsize * 2 * sizeof(uint64_t));
+ if (Phc == NULL) {
+ PyErr_NoMemory();
+ return -1;
+ }
+ Mhc = Phc + hsize;
+ memset(Phc, -1, hsize * sizeof(uint64_t));
+ memset(Mhc, 0, hsize * sizeof(uint64_t));
+ Last = (uint64_t)1 << ((s2->len - 1) % 64);
+
+ for (b = 0; b < vsize; b++) {
+ Mv = 0;
+ Pv = (uint64_t) -1;
+ Score = s2->len;
+
+ for (i = 0; i < s1->len; i++) {
+ Eq = blockmap_get(map, b, strbuf_read(s1, i));
+
+ Pb = BIT(Phc[i / 64], i % 64);
+ Mb = BIT(Mhc[i / 64], i % 64);
+
+ Xv = Eq | Mv;
+ Xh = ((((Eq | Mb) & Pv) + Pv) ^ Pv) | Eq | Mb;
+
+ Ph = Mv | ~ (Xh | Pv);
+ Mh = Pv & Xh;
+
+ if (Ph & Last) Score++;
+ if (Mh & Last) Score--;
+
+ if ((Ph >> 63) ^ Pb)
+ Phc[i / 64] = FLIP(Phc[i / 64], i % 64);
+
+ if ((Mh >> 63) ^ Mb)
+ Mhc[i / 64] = FLIP(Mhc[i / 64], i % 64);
+
+ Ph = (Ph << 1) | Pb;
+ Mh = (Mh << 1) | Mb;
+
+ Pv = Mh | ~ (Xv | Ph);
+ Mv = Ph & Xv;
+ }
+ }
+ free(Phc);
+ return Score;
+}
+
+static int64_t myers1999_simple(uint8_t *s1, int64_t len1, uint8_t *s2, int64_t len2)
+{
+ uint64_t Peq[256];
+ uint64_t Eq, Xv, Xh, Ph, Mh, Pv, Mv, Last;
+ int64_t i;
+ int64_t Score = len2;
+
+ memset(Peq, 0, sizeof(Peq));
+
+ for (i = 0; i < len2; i++)
+ Peq[s2[i]] |= (uint64_t) 1 << i;
+
+ Mv = 0;
+ Pv = (uint64_t) -1;
+ Last = (uint64_t) 1 << (len2 - 1);
+
+ for (i = 0; i < len1; i++) {
+ Eq = Peq[s1[i]];
+
+ Xv = Eq | Mv;
+ Xh = (((Eq & Pv) + Pv) ^ Pv) | Eq;
+
+ Ph = Mv | ~ (Xh | Pv);
+ Mh = Pv & Xh;
+
+ if (Ph & Last) Score++;
+ if (Mh & Last) Score--;
+
+ Ph = (Ph << 1) | 1;
+ Mh = (Mh << 1);
+
+ Pv = Mh | ~ (Xv | Ph);
+ Mv = Ph & Xv;
+ }
+ return Score;
+}
+
+static int64_t myers1999(PyObject *o1, PyObject *o2)
+{
+ struct strbuf s1, s2;
+ struct blockmap map;
+ int64_t ret;
+
+ strbuf_init(&s1, o1);
+ strbuf_init(&s2, o2);
+
+ if (s1.len < s2.len)
+ return myers1999(o2, o1);
+
+ if (ISASCII(s1.kind) && ISASCII(s2.kind) && s2.len < 65)
+ return myers1999_simple(s1.ptr, s1.len, s2.ptr, s2.len);
+
+ if (blockmap_init(&map, &s2))
+ return -1;
+
+ ret = myers1999_block(&s1, &s2, &map);
+ blockmap_clear(&map);
+ return ret;
+}
+
+/*
+ * Interface functions
+ */
+static int64_t polyleven(PyObject *o1, PyObject *o2, int64_t k)
+{
+ int64_t len1, len2;
+
+ len1 = PyUnicode_GET_LENGTH(o1);
+ len2 = PyUnicode_GET_LENGTH(o2);
+
+ if (len1 < len2)
+ return polyleven(o2, o1, k);
+
+ if (k == 0)
+ return PyUnicode_Compare(o1, o2) ? 1 : 0;
+
+ if (0 < k && k < len1 - len2)
+ return k + 1;
+
+ if (len2 == 0)
+ return len1;
+
+ if (0 < k && k < 4)
+ return mbleven(o1, o2, k);
+
+ return myers1999(o1, o2);
+}
diff --git a/spacy/ml/_precomputable_affine.py b/spacy/ml/_precomputable_affine.py
index b99de2d2b..1c20c622b 100644
--- a/spacy/ml/_precomputable_affine.py
+++ b/spacy/ml/_precomputable_affine.py
@@ -22,9 +22,15 @@ def forward(model, X, is_train):
nP = model.get_dim("nP")
nI = model.get_dim("nI")
W = model.get_param("W")
- Yf = model.ops.gemm(X, W.reshape((nF * nO * nP, nI)), trans2=True)
+ # Preallocate array for layer output, including padding.
+ Yf = model.ops.alloc2f(X.shape[0] + 1, nF * nO * nP, zeros=False)
+ model.ops.gemm(X, W.reshape((nF * nO * nP, nI)), trans2=True, out=Yf[1:])
Yf = Yf.reshape((Yf.shape[0], nF, nO, nP))
- Yf = model.ops.xp.vstack((model.get_param("pad"), Yf))
+
+ # Set padding. Padding has shape (1, nF, nO, nP). Unfortunately, we cannot
+ # change its shape to (nF, nO, nP) without breaking existing models. So
+ # we'll squeeze the first dimension here.
+ Yf[0] = model.ops.xp.squeeze(model.get_param("pad"), 0)
def backward(dY_ids):
# This backprop is particularly tricky, because we get back a different
diff --git a/spacy/ml/callbacks.py b/spacy/ml/callbacks.py
index b0d088182..3b60ec2ab 100644
--- a/spacy/ml/callbacks.py
+++ b/spacy/ml/callbacks.py
@@ -1,9 +1,14 @@
-from functools import partial
-from typing import Type, Callable, TYPE_CHECKING
+from typing import Type, Callable, Dict, TYPE_CHECKING, List, Optional, Set
+import functools
+import inspect
+import types
+import warnings
from thinc.layers import with_nvtx_range
from thinc.model import Model, wrap_model_recursive
+from thinc.util import use_nvtx_range
+from ..errors import Warnings
from ..util import registry
if TYPE_CHECKING:
@@ -11,29 +16,109 @@ if TYPE_CHECKING:
from ..language import Language # noqa: F401
-@registry.callbacks("spacy.models_with_nvtx_range.v1")
-def create_models_with_nvtx_range(
- forward_color: int = -1, backprop_color: int = -1
-) -> Callable[["Language"], "Language"]:
- def models_with_nvtx_range(nlp):
- pipes = [
- pipe
- for _, pipe in nlp.components
- if hasattr(pipe, "is_trainable") and pipe.is_trainable
- ]
+DEFAULT_NVTX_ANNOTATABLE_PIPE_METHODS = [
+ "pipe",
+ "predict",
+ "set_annotations",
+ "update",
+ "rehearse",
+ "get_loss",
+ "initialize",
+ "begin_update",
+ "finish_update",
+ "update",
+]
- # We need process all models jointly to avoid wrapping callbacks twice.
- models = Model(
- "wrap_with_nvtx_range",
- forward=lambda model, X, is_train: ...,
- layers=[pipe.model for pipe in pipes],
- )
- for node in models.walk():
+def models_with_nvtx_range(nlp, forward_color: int, backprop_color: int):
+ pipes = [
+ pipe
+ for _, pipe in nlp.components
+ if hasattr(pipe, "is_trainable") and pipe.is_trainable
+ ]
+
+ seen_models: Set[int] = set()
+ for pipe in pipes:
+ for node in pipe.model.walk():
+ if id(node) in seen_models:
+ continue
+ seen_models.add(id(node))
with_nvtx_range(
node, forward_color=forward_color, backprop_color=backprop_color
)
+ return nlp
+
+
+@registry.callbacks("spacy.models_with_nvtx_range.v1")
+def create_models_with_nvtx_range(
+ forward_color: int = -1, backprop_color: int = -1
+) -> Callable[["Language"], "Language"]:
+ return functools.partial(
+ models_with_nvtx_range,
+ forward_color=forward_color,
+ backprop_color=backprop_color,
+ )
+
+
+def nvtx_range_wrapper_for_pipe_method(self, func, *args, **kwargs):
+ if isinstance(func, functools.partial):
+ return func(*args, **kwargs)
+ else:
+ with use_nvtx_range(f"{self.name} {func.__name__}"):
+ return func(*args, **kwargs)
+
+
+def pipes_with_nvtx_range(
+ nlp, additional_pipe_functions: Optional[Dict[str, List[str]]]
+):
+ for _, pipe in nlp.components:
+ if additional_pipe_functions:
+ extra_funcs = additional_pipe_functions.get(pipe.name, [])
+ else:
+ extra_funcs = []
+
+ for name in DEFAULT_NVTX_ANNOTATABLE_PIPE_METHODS + extra_funcs:
+ func = getattr(pipe, name, None)
+ if func is None:
+ if name in extra_funcs:
+ warnings.warn(Warnings.W121.format(method=name, pipe=pipe.name))
+ continue
+
+ wrapped_func = functools.partial(
+ types.MethodType(nvtx_range_wrapper_for_pipe_method, pipe), func
+ )
+
+ # We need to preserve the original function signature so that
+ # the original parameters are passed to pydantic for validation downstream.
+ try:
+ wrapped_func.__signature__ = inspect.signature(func) # type: ignore
+ except:
+ # Can fail for Cython methods that do not have bindings.
+ warnings.warn(Warnings.W122.format(method=name, pipe=pipe.name))
+ continue
+
+ try:
+ setattr(
+ pipe,
+ name,
+ wrapped_func,
+ )
+ except AttributeError:
+ warnings.warn(Warnings.W122.format(method=name, pipe=pipe.name))
+
+ return nlp
+
+
+@registry.callbacks("spacy.models_and_pipes_with_nvtx_range.v1")
+def create_models_and_pipes_with_nvtx_range(
+ forward_color: int = -1,
+ backprop_color: int = -1,
+ additional_pipe_functions: Optional[Dict[str, List[str]]] = None,
+) -> Callable[["Language"], "Language"]:
+ def inner(nlp):
+ nlp = models_with_nvtx_range(nlp, forward_color, backprop_color)
+ nlp = pipes_with_nvtx_range(nlp, additional_pipe_functions)
return nlp
- return models_with_nvtx_range
+ return inner
diff --git a/spacy/ml/extract_spans.py b/spacy/ml/extract_spans.py
index edc86ff9c..d5e9bc07c 100644
--- a/spacy/ml/extract_spans.py
+++ b/spacy/ml/extract_spans.py
@@ -63,4 +63,4 @@ def _get_span_indices(ops, spans: Ragged, lengths: Ints1d) -> Ints1d:
def _ensure_cpu(spans: Ragged, lengths: Ints1d) -> Tuple[Ragged, Ints1d]:
- return (Ragged(to_numpy(spans.dataXd), to_numpy(spans.lengths)), to_numpy(lengths))
+ return Ragged(to_numpy(spans.dataXd), to_numpy(spans.lengths)), to_numpy(lengths)
diff --git a/spacy/ml/models/entity_linker.py b/spacy/ml/models/entity_linker.py
index 831fee90f..299b6bb52 100644
--- a/spacy/ml/models/entity_linker.py
+++ b/spacy/ml/models/entity_linker.py
@@ -1,38 +1,88 @@
from pathlib import Path
-from typing import Optional, Callable, Iterable, List
+from typing import Optional, Callable, Iterable, List, Tuple
from thinc.types import Floats2d
-from thinc.api import chain, clone, list2ragged, reduce_mean, residual
-from thinc.api import Model, Maxout, Linear
+from thinc.api import chain, list2ragged, reduce_mean, residual
+from thinc.api import Model, Maxout, Linear, tuplify, Ragged
from ...util import registry
-from ...kb import KnowledgeBase, Candidate, get_candidates
+from ...kb import KnowledgeBase, InMemoryLookupKB
+from ...kb import Candidate, get_candidates, get_candidates_batch
from ...vocab import Vocab
from ...tokens import Span, Doc
+from ..extract_spans import extract_spans
+from ...errors import Errors
-@registry.architectures("spacy.EntityLinker.v1")
+@registry.architectures("spacy.EntityLinker.v2")
def build_nel_encoder(
tok2vec: Model, nO: Optional[int] = None
) -> Model[List[Doc], Floats2d]:
- with Model.define_operators({">>": chain, "**": clone}):
+ with Model.define_operators({">>": chain, "&": tuplify}):
token_width = tok2vec.maybe_get_dim("nO")
output_layer = Linear(nO=nO, nI=token_width)
model = (
- tok2vec
- >> list2ragged()
+ ((tok2vec >> list2ragged()) & build_span_maker())
+ >> extract_spans()
>> reduce_mean()
- >> residual(Maxout(nO=token_width, nI=token_width, nP=2, dropout=0.0)) # type: ignore[arg-type]
+ >> residual(Maxout(nO=token_width, nI=token_width, nP=2, dropout=0.0)) # type: ignore
>> output_layer
)
model.set_ref("output_layer", output_layer)
model.set_ref("tok2vec", tok2vec)
+ # flag to show this isn't legacy
+ model.attrs["include_span_maker"] = True
return model
+def build_span_maker(n_sents: int = 0) -> Model:
+ model: Model = Model("span_maker", forward=span_maker_forward)
+ model.attrs["n_sents"] = n_sents
+ return model
+
+
+def span_maker_forward(model, docs: List[Doc], is_train) -> Tuple[Ragged, Callable]:
+ ops = model.ops
+ n_sents = model.attrs["n_sents"]
+ candidates = []
+ for doc in docs:
+ cands = []
+ try:
+ sentences = [s for s in doc.sents]
+ except ValueError:
+ # no sentence info, normal in initialization
+ for tok in doc:
+ tok.is_sent_start = tok.i == 0
+ sentences = [doc[:]]
+ for ent in doc.ents:
+ try:
+ # find the sentence in the list of sentences.
+ sent_index = sentences.index(ent.sent)
+ except AttributeError:
+ # Catch the exception when ent.sent is None and provide a user-friendly warning
+ raise RuntimeError(Errors.E030) from None
+ # get n previous sentences, if there are any
+ start_sentence = max(0, sent_index - n_sents)
+ # get n posterior sentences, or as many < n as there are
+ end_sentence = min(len(sentences) - 1, sent_index + n_sents)
+ # get token positions
+ start_token = sentences[start_sentence].start
+ end_token = sentences[end_sentence].end
+ # save positions for extraction
+ cands.append((start_token, end_token))
+
+ candidates.append(ops.asarray2i(cands))
+ lengths = model.ops.asarray1i([len(cands) for cands in candidates])
+ out = Ragged(model.ops.flatten(candidates), lengths)
+ # because this is just rearranging docs, the backprop does nothing
+ return out, lambda x: []
+
+
@registry.misc("spacy.KBFromFile.v1")
-def load_kb(kb_path: Path) -> Callable[[Vocab], KnowledgeBase]:
- def kb_from_file(vocab):
- kb = KnowledgeBase(vocab, entity_vector_length=1)
+def load_kb(
+ kb_path: Path,
+) -> Callable[[Vocab], KnowledgeBase]:
+ def kb_from_file(vocab: Vocab):
+ kb = InMemoryLookupKB(vocab, entity_vector_length=1)
kb.from_disk(kb_path)
return kb
@@ -40,9 +90,11 @@ def load_kb(kb_path: Path) -> Callable[[Vocab], KnowledgeBase]:
@registry.misc("spacy.EmptyKB.v1")
-def empty_kb(entity_vector_length: int) -> Callable[[Vocab], KnowledgeBase]:
- def empty_kb_factory(vocab):
- return KnowledgeBase(vocab=vocab, entity_vector_length=entity_vector_length)
+def empty_kb(
+ entity_vector_length: int,
+) -> Callable[[Vocab], KnowledgeBase]:
+ def empty_kb_factory(vocab: Vocab):
+ return InMemoryLookupKB(vocab=vocab, entity_vector_length=entity_vector_length)
return empty_kb_factory
@@ -50,3 +102,10 @@ def empty_kb(entity_vector_length: int) -> Callable[[Vocab], KnowledgeBase]:
@registry.misc("spacy.CandidateGenerator.v1")
def create_candidates() -> Callable[[KnowledgeBase, Span], Iterable[Candidate]]:
return get_candidates
+
+
+@registry.misc("spacy.CandidateBatchGenerator.v1")
+def create_candidates_batch() -> Callable[
+ [KnowledgeBase, Iterable[Span]], Iterable[Iterable[Candidate]]
+]:
+ return get_candidates_batch
diff --git a/spacy/ml/models/parser.py b/spacy/ml/models/parser.py
index 63284e766..a70d84dea 100644
--- a/spacy/ml/models/parser.py
+++ b/spacy/ml/models/parser.py
@@ -72,7 +72,7 @@ def build_tb_parser_model(
t2v_width = tok2vec.get_dim("nO") if tok2vec.has_dim("nO") else None
tok2vec = chain(
tok2vec,
- cast(Model[List["Floats2d"], Floats2d], list2array()),
+ list2array(),
Linear(hidden_width, t2v_width),
)
tok2vec.set_dim("nO", hidden_width)
diff --git a/spacy/ml/models/tagger.py b/spacy/ml/models/tagger.py
index 9c7fe042d..9f8ef7b2b 100644
--- a/spacy/ml/models/tagger.py
+++ b/spacy/ml/models/tagger.py
@@ -1,14 +1,14 @@
from typing import Optional, List
-from thinc.api import zero_init, with_array, Softmax, chain, Model
+from thinc.api import zero_init, with_array, Softmax_v2, chain, Model
from thinc.types import Floats2d
from ...util import registry
from ...tokens import Doc
-@registry.architectures("spacy.Tagger.v1")
+@registry.architectures("spacy.Tagger.v2")
def build_tagger_model(
- tok2vec: Model[List[Doc], List[Floats2d]], nO: Optional[int] = None
+ tok2vec: Model[List[Doc], List[Floats2d]], nO: Optional[int] = None, normalize=False
) -> Model[List[Doc], List[Floats2d]]:
"""Build a tagger model, using a provided token-to-vector component. The tagger
model simply adds a linear layer with softmax activation to predict scores
@@ -19,7 +19,9 @@ def build_tagger_model(
"""
# TODO: glorot_uniform_init seems to work a bit better than zero_init here?!
t2v_width = tok2vec.get_dim("nO") if tok2vec.has_dim("nO") else None
- output_layer = Softmax(nO, t2v_width, init_W=zero_init)
+ output_layer = Softmax_v2(
+ nO, t2v_width, init_W=zero_init, normalize_outputs=normalize
+ )
softmax = with_array(output_layer) # type: ignore
model = chain(tok2vec, softmax)
model.set_ref("tok2vec", tok2vec)
diff --git a/spacy/ml/models/textcat.py b/spacy/ml/models/textcat.py
index c8c146f02..9c7e607fe 100644
--- a/spacy/ml/models/textcat.py
+++ b/spacy/ml/models/textcat.py
@@ -1,5 +1,5 @@
+from typing import Optional, List, cast
from functools import partial
-from typing import Optional, List
from thinc.types import Floats2d
from thinc.api import Model, reduce_mean, Linear, list2ragged, Logistic
@@ -59,7 +59,8 @@ def build_simple_cnn_text_classifier(
resizable_layer=resizable_layer,
)
model.set_ref("tok2vec", tok2vec)
- model.set_dim("nO", nO) # type: ignore # TODO: remove type ignore once Thinc has been updated
+ if nO is not None:
+ model.set_dim("nO", cast(int, nO))
model.attrs["multi_label"] = not exclusive_classes
return model
@@ -85,7 +86,7 @@ def build_bow_text_classifier(
if not no_output_layer:
fill_defaults["b"] = NEG_VALUE
output_layer = softmax_activation() if exclusive_classes else Logistic()
- resizable_layer = resizable( # type: ignore[var-annotated]
+ resizable_layer: Model[Floats2d, Floats2d] = resizable(
sparse_linear,
resize_layer=partial(resize_linear_weighted, fill_defaults=fill_defaults),
)
@@ -93,7 +94,8 @@ def build_bow_text_classifier(
model = with_cpu(model, model.ops)
if output_layer:
model = model >> with_cpu(output_layer, output_layer.ops)
- model.set_dim("nO", nO) # type: ignore[arg-type]
+ if nO is not None:
+ model.set_dim("nO", cast(int, nO))
model.set_ref("output_layer", sparse_linear)
model.attrs["multi_label"] = not exclusive_classes
model.attrs["resize_output"] = partial(
@@ -129,8 +131,8 @@ def build_text_classifier_v2(
output_layer = Linear(nO=nO, nI=nO_double) >> Logistic()
model = (linear_model | cnn_model) >> output_layer
model.set_ref("tok2vec", tok2vec)
- if model.has_dim("nO") is not False:
- model.set_dim("nO", nO) # type: ignore[arg-type]
+ if model.has_dim("nO") is not False and nO is not None:
+ model.set_dim("nO", cast(int, nO))
model.set_ref("output_layer", linear_model.get_ref("output_layer"))
model.set_ref("attention_layer", attention_layer)
model.set_ref("maxout_layer", maxout_layer)
@@ -164,7 +166,7 @@ def build_text_classifier_lowdata(
>> list2ragged()
>> ParametricAttention(width)
>> reduce_sum()
- >> residual(Relu(width, width)) ** 2 # type: ignore[arg-type]
+ >> residual(Relu(width, width)) ** 2
>> Linear(nO, width)
)
if dropout:
diff --git a/spacy/ml/models/tok2vec.py b/spacy/ml/models/tok2vec.py
index ecdf6be27..30c7360ff 100644
--- a/spacy/ml/models/tok2vec.py
+++ b/spacy/ml/models/tok2vec.py
@@ -1,5 +1,5 @@
from typing import Optional, List, Union, cast
-from thinc.types import Floats2d, Ints2d, Ragged
+from thinc.types import Floats2d, Ints2d, Ragged, Ints1d
from thinc.api import chain, clone, concatenate, with_array, with_padded
from thinc.api import Model, noop, list2ragged, ragged2list, HashEmbed
from thinc.api import expand_window, residual, Maxout, Mish, PyTorchLSTM
@@ -159,7 +159,7 @@ def MultiHashEmbed(
embeddings = [make_hash_embed(i) for i in range(len(attrs))]
concat_size = width * (len(embeddings) + include_static_vectors)
max_out: Model[Ragged, Ragged] = with_array(
- Maxout(width, concat_size, nP=3, dropout=0.0, normalize=True) # type: ignore
+ Maxout(width, concat_size, nP=3, dropout=0.0, normalize=True)
)
if include_static_vectors:
feature_extractor: Model[List[Doc], Ragged] = chain(
@@ -173,7 +173,7 @@ def MultiHashEmbed(
StaticVectors(width, dropout=0.0),
),
max_out,
- cast(Model[Ragged, List[Floats2d]], ragged2list()),
+ ragged2list(),
)
else:
model = chain(
@@ -181,7 +181,7 @@ def MultiHashEmbed(
cast(Model[List[Ints2d], Ragged], list2ragged()),
with_array(concatenate(*embeddings)),
max_out,
- cast(Model[Ragged, List[Floats2d]], ragged2list()),
+ ragged2list(),
)
return model
@@ -232,12 +232,12 @@ def CharacterEmbed(
feature_extractor: Model[List[Doc], Ragged] = chain(
FeatureExtractor([feature]),
cast(Model[List[Ints2d], Ragged], list2ragged()),
- with_array(HashEmbed(nO=width, nV=rows, column=0, seed=5)), # type: ignore
+ with_array(HashEmbed(nO=width, nV=rows, column=0, seed=5)), # type: ignore[misc]
)
max_out: Model[Ragged, Ragged]
if include_static_vectors:
max_out = with_array(
- Maxout(width, nM * nC + (2 * width), nP=3, normalize=True, dropout=0.0) # type: ignore
+ Maxout(width, nM * nC + (2 * width), nP=3, normalize=True, dropout=0.0)
)
model = chain(
concatenate(
@@ -246,11 +246,11 @@ def CharacterEmbed(
StaticVectors(width, dropout=0.0),
),
max_out,
- cast(Model[Ragged, List[Floats2d]], ragged2list()),
+ ragged2list(),
)
else:
max_out = with_array(
- Maxout(width, nM * nC + width, nP=3, normalize=True, dropout=0.0) # type: ignore
+ Maxout(width, nM * nC + width, nP=3, normalize=True, dropout=0.0)
)
model = chain(
concatenate(
@@ -258,7 +258,7 @@ def CharacterEmbed(
feature_extractor,
),
max_out,
- cast(Model[Ragged, List[Floats2d]], ragged2list()),
+ ragged2list(),
)
return model
@@ -289,10 +289,10 @@ def MaxoutWindowEncoder(
normalize=True,
),
)
- model = clone(residual(cnn), depth) # type: ignore[arg-type]
+ model = clone(residual(cnn), depth)
model.set_dim("nO", width)
receptive_field = window_size * depth
- return with_array(model, pad=receptive_field) # type: ignore[arg-type]
+ return with_array(model, pad=receptive_field)
@registry.architectures("spacy.MishWindowEncoder.v2")
@@ -313,9 +313,9 @@ def MishWindowEncoder(
expand_window(window_size=window_size),
Mish(nO=width, nI=width * ((window_size * 2) + 1), dropout=0.0, normalize=True),
)
- model = clone(residual(cnn), depth) # type: ignore[arg-type]
+ model = clone(residual(cnn), depth)
model.set_dim("nO", width)
- return with_array(model) # type: ignore[arg-type]
+ return with_array(model)
@registry.architectures("spacy.TorchBiLSTMEncoder.v1")
diff --git a/spacy/ml/parser_model.pxd b/spacy/ml/parser_model.pxd
index 6582b3468..8def6cea5 100644
--- a/spacy/ml/parser_model.pxd
+++ b/spacy/ml/parser_model.pxd
@@ -1,4 +1,5 @@
from libc.string cimport memset, memcpy
+from thinc.backends.cblas cimport CBlas
from ..typedefs cimport weight_t, hash_t
from ..pipeline._parser_internals._state cimport StateC
@@ -38,7 +39,7 @@ cdef ActivationsC alloc_activations(SizesC n) nogil
cdef void free_activations(const ActivationsC* A) nogil
-cdef void predict_states(ActivationsC* A, StateC** states,
+cdef void predict_states(CBlas cblas, ActivationsC* A, StateC** states,
const WeightsC* W, SizesC n) nogil
cdef int arg_max_if_valid(const weight_t* scores, const int* is_valid, int n) nogil
diff --git a/spacy/ml/parser_model.pyx b/spacy/ml/parser_model.pyx
index da937ca4f..961bf4d70 100644
--- a/spacy/ml/parser_model.pyx
+++ b/spacy/ml/parser_model.pyx
@@ -4,13 +4,14 @@ from libc.math cimport exp
from libc.string cimport memset, memcpy
from libc.stdlib cimport calloc, free, realloc
from thinc.backends.linalg cimport Vec, VecVec
-cimport blis.cy
+from thinc.backends.cblas cimport saxpy, sgemm
import numpy
import numpy.random
-from thinc.api import Model, CupyOps, NumpyOps
+from thinc.api import Model, CupyOps, NumpyOps, get_ops
from .. import util
+from ..errors import Errors
from ..typedefs cimport weight_t, class_t, hash_t
from ..pipeline._parser_internals.stateclass cimport StateClass
@@ -90,7 +91,7 @@ cdef void resize_activations(ActivationsC* A, SizesC n) nogil:
A._curr_size = n.states
-cdef void predict_states(ActivationsC* A, StateC** states,
+cdef void predict_states(CBlas cblas, ActivationsC* A, StateC** states,
const WeightsC* W, SizesC n) nogil:
cdef double one = 1.0
resize_activations(A, n)
@@ -98,7 +99,7 @@ cdef void predict_states(ActivationsC* A, StateC** states,
states[i].set_context_tokens(&A.token_ids[i*n.feats], n.feats)
memset(A.unmaxed, 0, n.states * n.hiddens * n.pieces * sizeof(float))
memset(A.hiddens, 0, n.states * n.hiddens * sizeof(float))
- sum_state_features(A.unmaxed,
+ sum_state_features(cblas, A.unmaxed,
W.feat_weights, A.token_ids, n.states, n.feats, n.hiddens * n.pieces)
for i in range(n.states):
VecVec.add_i(&A.unmaxed[i*n.hiddens*n.pieces],
@@ -112,12 +113,10 @@ cdef void predict_states(ActivationsC* A, StateC** states,
memcpy(A.scores, A.hiddens, n.states * n.classes * sizeof(float))
else:
# Compute hidden-to-output
- blis.cy.gemm(blis.cy.NO_TRANSPOSE, blis.cy.TRANSPOSE,
- n.states, n.classes, n.hiddens, one,
- A.hiddens, n.hiddens, 1,
- W.hidden_weights, n.hiddens, 1,
- one,
- A.scores, n.classes, 1)
+ sgemm(cblas)(False, True, n.states, n.classes, n.hiddens,
+ 1.0, A.hiddens, n.hiddens,
+ W.hidden_weights, n.hiddens,
+ 0.0, A.scores, n.classes)
# Add bias
for i in range(n.states):
VecVec.add_i(&A.scores[i*n.classes],
@@ -134,7 +133,7 @@ cdef void predict_states(ActivationsC* A, StateC** states,
A.scores[i*n.classes+j] = min_
-cdef void sum_state_features(float* output,
+cdef void sum_state_features(CBlas cblas, float* output,
const float* cached, const int* token_ids, int B, int F, int O) nogil:
cdef int idx, b, f, i
cdef const float* feature
@@ -149,9 +148,7 @@ cdef void sum_state_features(float* output,
else:
idx = token_ids[f] * id_stride + f*O
feature = &cached[idx]
- blis.cy.axpyv(blis.cy.NO_CONJUGATE, O, one,
- feature, 1,
- &output[b*O], 1)
+ saxpy(cblas)(O, one, feature, 1, &output[b*O], 1)
token_ids += F
@@ -411,7 +408,7 @@ cdef class precompute_hiddens:
elif name == "nO":
return self.nO
else:
- raise ValueError(f"Dimension {name} invalid -- only nO, nF, nP")
+ raise ValueError(Errors.E1033.format(name=name))
def set_dim(self, name, value):
if name == "nF":
@@ -421,7 +418,7 @@ cdef class precompute_hiddens:
elif name == "nO":
self.nO = value
else:
- raise ValueError(f"Dimension {name} invalid -- only nO, nF, nP")
+ raise ValueError(Errors.E1033.format(name=name))
def __call__(self, X, bint is_train):
if is_train:
@@ -442,9 +439,15 @@ cdef class precompute_hiddens:
# - Output from backward on GPU
bp_hiddens = self._bp_hiddens
+ cdef CBlas cblas
+ if isinstance(self.ops, CupyOps):
+ cblas = NUMPY_OPS.cblas()
+ else:
+ cblas = self.ops.cblas()
+
feat_weights = self.get_feat_weights()
cdef int[:, ::1] ids = token_ids
- sum_state_features(state_vector.data,
+ sum_state_features(cblas, state_vector.data,
feat_weights, &ids[0,0],
token_ids.shape[0], self.nF, self.nO*self.nP)
state_vector += self.bias
diff --git a/spacy/ml/staticvectors.py b/spacy/ml/staticvectors.py
index 8d9b1af9b..04cfe912d 100644
--- a/spacy/ml/staticvectors.py
+++ b/spacy/ml/staticvectors.py
@@ -40,17 +40,15 @@ def forward(
if not token_count:
return _handle_empty(model.ops, model.get_dim("nO"))
key_attr: int = model.attrs["key_attr"]
- keys: Ints1d = model.ops.flatten(
- cast(Sequence, [doc.to_array(key_attr) for doc in docs])
- )
+ keys = model.ops.flatten([cast(Ints1d, doc.to_array(key_attr)) for doc in docs])
vocab: Vocab = docs[0].vocab
W = cast(Floats2d, model.ops.as_contig(model.get_param("W")))
if vocab.vectors.mode == Mode.default:
- V = cast(Floats2d, model.ops.asarray(vocab.vectors.data))
+ V = model.ops.asarray(vocab.vectors.data)
rows = vocab.vectors.find(keys=keys)
V = model.ops.as_contig(V[rows])
elif vocab.vectors.mode == Mode.floret:
- V = cast(Floats2d, vocab.vectors.get_batch(keys))
+ V = vocab.vectors.get_batch(keys)
V = model.ops.as_contig(V)
else:
raise RuntimeError(Errors.E896)
@@ -62,9 +60,7 @@ def forward(
# Convert negative indices to 0-vectors
# TODO: more options for UNK tokens
vectors_data[rows < 0] = 0
- output = Ragged(
- vectors_data, model.ops.asarray([len(doc) for doc in docs], dtype="i") # type: ignore
- )
+ output = Ragged(vectors_data, model.ops.asarray1i([len(doc) for doc in docs]))
mask = None
if is_train:
mask = _get_drop_mask(model.ops, W.shape[0], model.attrs.get("dropout_rate"))
@@ -77,7 +73,9 @@ def forward(
model.inc_grad(
"W",
model.ops.gemm(
- cast(Floats2d, d_output.data), model.ops.as_contig(V), trans1=True
+ cast(Floats2d, d_output.data),
+ cast(Floats2d, model.ops.as_contig(V)),
+ trans1=True,
),
)
return []
diff --git a/spacy/pipeline/__init__.py b/spacy/pipeline/__init__.py
index 7b483724c..26931606b 100644
--- a/spacy/pipeline/__init__.py
+++ b/spacy/pipeline/__init__.py
@@ -1,5 +1,6 @@
from .attributeruler import AttributeRuler
from .dep_parser import DependencyParser
+from .edit_tree_lemmatizer import EditTreeLemmatizer
from .entity_linker import EntityLinker
from .ner import EntityRecognizer
from .entityruler import EntityRuler
@@ -12,6 +13,7 @@ from .sentencizer import Sentencizer
from .tagger import Tagger
from .textcat import TextCategorizer
from .spancat import SpanCategorizer
+from .span_ruler import SpanRuler
from .textcat_multilabel import MultiLabel_TextCategorizer
from .tok2vec import Tok2Vec
from .functions import merge_entities, merge_noun_chunks, merge_subtokens
@@ -29,6 +31,7 @@ __all__ = [
"SentenceRecognizer",
"Sentencizer",
"SpanCategorizer",
+ "SpanRuler",
"Tagger",
"TextCategorizer",
"Tok2Vec",
diff --git a/spacy/pipeline/_edit_tree_internals/__init__.py b/spacy/pipeline/_edit_tree_internals/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/spacy/pipeline/_edit_tree_internals/edit_trees.pxd b/spacy/pipeline/_edit_tree_internals/edit_trees.pxd
new file mode 100644
index 000000000..dc4289f37
--- /dev/null
+++ b/spacy/pipeline/_edit_tree_internals/edit_trees.pxd
@@ -0,0 +1,93 @@
+from libc.stdint cimport uint32_t, uint64_t
+from libcpp.unordered_map cimport unordered_map
+from libcpp.vector cimport vector
+
+from ...typedefs cimport attr_t, hash_t, len_t
+from ...strings cimport StringStore
+
+cdef extern from "" namespace "std" nogil:
+ void swap[T](T& a, T& b) except + # Only available in Cython 3.
+
+# An edit tree (Müller et al., 2015) is a tree structure that consists of
+# edit operations. The two types of operations are string matches
+# and string substitutions. Given an input string s and an output string t,
+# subsitution and match nodes should be interpreted as follows:
+#
+# * Substitution node: consists of an original string and substitute string.
+# If s matches the original string, then t is the substitute. Otherwise,
+# the node does not apply.
+# * Match node: consists of a prefix length, suffix length, prefix edit tree,
+# and suffix edit tree. If s is composed of a prefix, middle part, and suffix
+# with the given suffix and prefix lengths, then t is the concatenation
+# prefix_tree(prefix) + middle + suffix_tree(suffix).
+#
+# For efficiency, we represent strings in substitution nodes as integers, with
+# the actual strings stored in a StringStore. Subtrees in match nodes are stored
+# as tree identifiers (rather than pointers) to simplify serialization.
+
+cdef uint32_t NULL_TREE_ID
+
+cdef struct MatchNodeC:
+ len_t prefix_len
+ len_t suffix_len
+ uint32_t prefix_tree
+ uint32_t suffix_tree
+
+cdef struct SubstNodeC:
+ attr_t orig
+ attr_t subst
+
+cdef union NodeC:
+ MatchNodeC match_node
+ SubstNodeC subst_node
+
+cdef struct EditTreeC:
+ bint is_match_node
+ NodeC inner
+
+cdef inline EditTreeC edittree_new_match(len_t prefix_len, len_t suffix_len,
+ uint32_t prefix_tree, uint32_t suffix_tree):
+ cdef MatchNodeC match_node = MatchNodeC(prefix_len=prefix_len,
+ suffix_len=suffix_len, prefix_tree=prefix_tree,
+ suffix_tree=suffix_tree)
+ cdef NodeC inner = NodeC(match_node=match_node)
+ return EditTreeC(is_match_node=True, inner=inner)
+
+cdef inline EditTreeC edittree_new_subst(attr_t orig, attr_t subst):
+ cdef EditTreeC node
+ cdef SubstNodeC subst_node = SubstNodeC(orig=orig, subst=subst)
+ cdef NodeC inner = NodeC(subst_node=subst_node)
+ return EditTreeC(is_match_node=False, inner=inner)
+
+cdef inline uint64_t edittree_hash(EditTreeC tree):
+ cdef MatchNodeC match_node
+ cdef SubstNodeC subst_node
+
+ if tree.is_match_node:
+ match_node = tree.inner.match_node
+ return hash((match_node.prefix_len, match_node.suffix_len, match_node.prefix_tree, match_node.suffix_tree))
+ else:
+ subst_node = tree.inner.subst_node
+ return hash((subst_node.orig, subst_node.subst))
+
+cdef struct LCS:
+ int source_begin
+ int source_end
+ int target_begin
+ int target_end
+
+cdef inline bint lcs_is_empty(LCS lcs):
+ return lcs.source_begin == 0 and lcs.source_end == 0 and lcs.target_begin == 0 and lcs.target_end == 0
+
+cdef class EditTrees:
+ cdef vector[EditTreeC] trees
+ cdef unordered_map[hash_t, uint32_t] map
+ cdef StringStore strings
+
+ cpdef uint32_t add(self, str form, str lemma)
+ cpdef str apply(self, uint32_t tree_id, str form)
+ cpdef unicode tree_to_str(self, uint32_t tree_id)
+
+ cdef uint32_t _add(self, str form, str lemma)
+ cdef _apply(self, uint32_t tree_id, str form_part, list lemma_pieces)
+ cdef uint32_t _tree_id(self, EditTreeC tree)
diff --git a/spacy/pipeline/_edit_tree_internals/edit_trees.pyx b/spacy/pipeline/_edit_tree_internals/edit_trees.pyx
new file mode 100644
index 000000000..9d18c0334
--- /dev/null
+++ b/spacy/pipeline/_edit_tree_internals/edit_trees.pyx
@@ -0,0 +1,305 @@
+# cython: infer_types=True, binding=True
+from cython.operator cimport dereference as deref
+from libc.stdint cimport uint32_t
+from libc.stdint cimport UINT32_MAX
+from libc.string cimport memset
+from libcpp.pair cimport pair
+from libcpp.vector cimport vector
+
+from pathlib import Path
+
+from ...typedefs cimport hash_t
+
+from ... import util
+from ...errors import Errors
+from ...strings import StringStore
+from .schemas import validate_edit_tree
+
+
+NULL_TREE_ID = UINT32_MAX
+
+cdef LCS find_lcs(str source, str target):
+ """
+ Find the longest common subsequence (LCS) between two strings. If there are
+ multiple LCSes, only one of them is returned.
+
+ source (str): The first string.
+ target (str): The second string.
+ RETURNS (LCS): The spans of the longest common subsequences.
+ """
+ cdef Py_ssize_t source_len = len(source)
+ cdef Py_ssize_t target_len = len(target)
+ cdef size_t longest_align = 0;
+ cdef int source_idx, target_idx
+ cdef LCS lcs
+ cdef Py_UCS4 source_cp, target_cp
+
+ memset(&lcs, 0, sizeof(lcs))
+
+ cdef vector[size_t] prev_aligns = vector[size_t](target_len);
+ cdef vector[size_t] cur_aligns = vector[size_t](target_len);
+
+ for (source_idx, source_cp) in enumerate(source):
+ for (target_idx, target_cp) in enumerate(target):
+ if source_cp == target_cp:
+ if source_idx == 0 or target_idx == 0:
+ cur_aligns[target_idx] = 1
+ else:
+ cur_aligns[target_idx] = prev_aligns[target_idx - 1] + 1
+
+ # Check if this is the longest alignment and replace previous
+ # best alignment when this is the case.
+ if cur_aligns[target_idx] > longest_align:
+ longest_align = cur_aligns[target_idx]
+ lcs.source_begin = source_idx - longest_align + 1
+ lcs.source_end = source_idx + 1
+ lcs.target_begin = target_idx - longest_align + 1
+ lcs.target_end = target_idx + 1
+ else:
+ # No match, we start with a zero-length alignment.
+ cur_aligns[target_idx] = 0
+ swap(prev_aligns, cur_aligns)
+
+ return lcs
+
+cdef class EditTrees:
+ """Container for constructing and storing edit trees."""
+ def __init__(self, strings: StringStore):
+ """Create a container for edit trees.
+
+ strings (StringStore): the string store to use."""
+ self.strings = strings
+
+ cpdef uint32_t add(self, str form, str lemma):
+ """Add an edit tree that rewrites the given string into the given lemma.
+
+ RETURNS (int): identifier of the edit tree in the container.
+ """
+ # Treat two empty strings as a special case. Generating an edit
+ # tree for identical strings results in a match node. However,
+ # since two empty strings have a zero-length LCS, a substitution
+ # node would be created. Since we do not want to clutter the
+ # recursive tree construction with logic for this case, handle
+ # it in this wrapper method.
+ if len(form) == 0 and len(lemma) == 0:
+ tree = edittree_new_match(0, 0, NULL_TREE_ID, NULL_TREE_ID)
+ return self._tree_id(tree)
+
+ return self._add(form, lemma)
+
+ cdef uint32_t _add(self, str form, str lemma):
+ cdef LCS lcs = find_lcs(form, lemma)
+
+ cdef EditTreeC tree
+ cdef uint32_t tree_id, prefix_tree, suffix_tree
+ if lcs_is_empty(lcs):
+ tree = edittree_new_subst(self.strings.add(form), self.strings.add(lemma))
+ else:
+ # If we have a non-empty LCS, such as "gooi" in "ge[gooi]d" and "[gooi]en",
+ # create edit trees for the prefix pair ("ge"/"") and the suffix pair ("d"/"en").
+ prefix_tree = NULL_TREE_ID
+ if lcs.source_begin != 0 or lcs.target_begin != 0:
+ prefix_tree = self.add(form[:lcs.source_begin], lemma[:lcs.target_begin])
+
+ suffix_tree = NULL_TREE_ID
+ if lcs.source_end != len(form) or lcs.target_end != len(lemma):
+ suffix_tree = self.add(form[lcs.source_end:], lemma[lcs.target_end:])
+
+ tree = edittree_new_match(lcs.source_begin, len(form) - lcs.source_end, prefix_tree, suffix_tree)
+
+ return self._tree_id(tree)
+
+ cdef uint32_t _tree_id(self, EditTreeC tree):
+ # If this tree has been constructed before, return its identifier.
+ cdef hash_t hash = edittree_hash(tree)
+ cdef unordered_map[hash_t, uint32_t].iterator iter = self.map.find(hash)
+ if iter != self.map.end():
+ return deref(iter).second
+
+ # The tree hasn't been seen before, store it.
+ cdef uint32_t tree_id = self.trees.size()
+ self.trees.push_back(tree)
+ self.map.insert(pair[hash_t, uint32_t](hash, tree_id))
+
+ return tree_id
+
+ cpdef str apply(self, uint32_t tree_id, str form):
+ """Apply an edit tree to a form.
+
+ tree_id (uint32_t): the identifier of the edit tree to apply.
+ form (str): the form to apply the edit tree to.
+ RETURNS (str): the transformer form or None if the edit tree
+ could not be applied to the form.
+ """
+ if tree_id >= self.trees.size():
+ raise IndexError(Errors.E1030)
+
+ lemma_pieces = []
+ try:
+ self._apply(tree_id, form, lemma_pieces)
+ except ValueError:
+ return None
+ return "".join(lemma_pieces)
+
+ cdef _apply(self, uint32_t tree_id, str form_part, list lemma_pieces):
+ """Recursively apply an edit tree to a form, adding pieces to
+ the lemma_pieces list."""
+ assert tree_id <= self.trees.size()
+
+ cdef EditTreeC tree = self.trees[tree_id]
+ cdef MatchNodeC match_node
+ cdef int suffix_start
+
+ if tree.is_match_node:
+ match_node = tree.inner.match_node
+
+ if match_node.prefix_len + match_node.suffix_len > len(form_part):
+ raise ValueError(Errors.E1029)
+
+ suffix_start = len(form_part) - match_node.suffix_len
+
+ if match_node.prefix_tree != NULL_TREE_ID:
+ self._apply(match_node.prefix_tree, form_part[:match_node.prefix_len], lemma_pieces)
+
+ lemma_pieces.append(form_part[match_node.prefix_len:suffix_start])
+
+ if match_node.suffix_tree != NULL_TREE_ID:
+ self._apply(match_node.suffix_tree, form_part[suffix_start:], lemma_pieces)
+ else:
+ if form_part == self.strings[tree.inner.subst_node.orig]:
+ lemma_pieces.append(self.strings[tree.inner.subst_node.subst])
+ else:
+ raise ValueError(Errors.E1029)
+
+ cpdef unicode tree_to_str(self, uint32_t tree_id):
+ """Return the tree as a string. The tree tree string is formatted
+ like an S-expression. This is primarily useful for debugging. Match
+ nodes have the following format:
+
+ (m prefix_len suffix_len prefix_tree suffix_tree)
+
+ Substitution nodes have the following format:
+
+ (s original substitute)
+
+ tree_id (uint32_t): the identifier of the edit tree.
+ RETURNS (str): the tree as an S-expression.
+ """
+
+ if tree_id >= self.trees.size():
+ raise IndexError(Errors.E1030)
+
+ cdef EditTreeC tree = self.trees[tree_id]
+ cdef SubstNodeC subst_node
+
+ if not tree.is_match_node:
+ subst_node = tree.inner.subst_node
+ return f"(s '{self.strings[subst_node.orig]}' '{self.strings[subst_node.subst]}')"
+
+ cdef MatchNodeC match_node = tree.inner.match_node
+
+ prefix_tree = "()"
+ if match_node.prefix_tree != NULL_TREE_ID:
+ prefix_tree = self.tree_to_str(match_node.prefix_tree)
+
+ suffix_tree = "()"
+ if match_node.suffix_tree != NULL_TREE_ID:
+ suffix_tree = self.tree_to_str(match_node.suffix_tree)
+
+ return f"(m {match_node.prefix_len} {match_node.suffix_len} {prefix_tree} {suffix_tree})"
+
+ def from_json(self, trees: list) -> "EditTrees":
+ self.trees.clear()
+
+ for tree in trees:
+ tree = _dict2tree(tree)
+ self.trees.push_back(tree)
+
+ self._rebuild_tree_map()
+
+ def from_bytes(self, bytes_data: bytes, *) -> "EditTrees":
+ def deserialize_trees(tree_dicts):
+ cdef EditTreeC c_tree
+ for tree_dict in tree_dicts:
+ c_tree = _dict2tree(tree_dict)
+ self.trees.push_back(c_tree)
+
+ deserializers = {}
+ deserializers["trees"] = lambda n: deserialize_trees(n)
+ util.from_bytes(bytes_data, deserializers, [])
+
+ self._rebuild_tree_map()
+
+ return self
+
+ def to_bytes(self, **kwargs) -> bytes:
+ tree_dicts = []
+ for tree in self.trees:
+ tree = _tree2dict(tree)
+ tree_dicts.append(tree)
+
+ serializers = {}
+ serializers["trees"] = lambda: tree_dicts
+
+ return util.to_bytes(serializers, [])
+
+ def to_disk(self, path, **kwargs) -> "EditTrees":
+ path = util.ensure_path(path)
+ with path.open("wb") as file_:
+ file_.write(self.to_bytes())
+
+ def from_disk(self, path, **kwargs) -> "EditTrees":
+ path = util.ensure_path(path)
+ if path.exists():
+ with path.open("rb") as file_:
+ data = file_.read()
+ return self.from_bytes(data)
+
+ return self
+
+ def __getitem__(self, idx):
+ return _tree2dict(self.trees[idx])
+
+ def __len__(self):
+ return self.trees.size()
+
+ def _rebuild_tree_map(self):
+ """Rebuild the tree hash -> tree id mapping"""
+ cdef EditTreeC c_tree
+ cdef uint32_t tree_id
+ cdef hash_t tree_hash
+
+ self.map.clear()
+
+ for tree_id in range(self.trees.size()):
+ c_tree = self.trees[tree_id]
+ tree_hash = edittree_hash(c_tree)
+ self.map.insert(pair[hash_t, uint32_t](tree_hash, tree_id))
+
+ def __reduce__(self):
+ return (unpickle_edittrees, (self.strings, self.to_bytes()))
+
+
+def unpickle_edittrees(strings, trees_data):
+ return EditTrees(strings).from_bytes(trees_data)
+
+
+def _tree2dict(tree):
+ if tree["is_match_node"]:
+ tree = tree["inner"]["match_node"]
+ else:
+ tree = tree["inner"]["subst_node"]
+ return(dict(tree))
+
+def _dict2tree(tree):
+ errors = validate_edit_tree(tree)
+ if errors:
+ raise ValueError(Errors.E1026.format(errors="\n".join(errors)))
+
+ tree = dict(tree)
+ if "prefix_len" in tree:
+ tree = {"is_match_node": True, "inner": {"match_node": tree}}
+ else:
+ tree = {"is_match_node": False, "inner": {"subst_node": tree}}
+
+ return tree
diff --git a/spacy/pipeline/_edit_tree_internals/schemas.py b/spacy/pipeline/_edit_tree_internals/schemas.py
new file mode 100644
index 000000000..c01d0632e
--- /dev/null
+++ b/spacy/pipeline/_edit_tree_internals/schemas.py
@@ -0,0 +1,44 @@
+from typing import Any, Dict, List, Union
+from collections import defaultdict
+from pydantic import BaseModel, Field, ValidationError
+from pydantic.types import StrictBool, StrictInt, StrictStr
+
+
+class MatchNodeSchema(BaseModel):
+ prefix_len: StrictInt = Field(..., title="Prefix length")
+ suffix_len: StrictInt = Field(..., title="Suffix length")
+ prefix_tree: StrictInt = Field(..., title="Prefix tree")
+ suffix_tree: StrictInt = Field(..., title="Suffix tree")
+
+ class Config:
+ extra = "forbid"
+
+
+class SubstNodeSchema(BaseModel):
+ orig: Union[int, StrictStr] = Field(..., title="Original substring")
+ subst: Union[int, StrictStr] = Field(..., title="Replacement substring")
+
+ class Config:
+ extra = "forbid"
+
+
+class EditTreeSchema(BaseModel):
+ __root__: Union[MatchNodeSchema, SubstNodeSchema]
+
+
+def validate_edit_tree(obj: Dict[str, Any]) -> List[str]:
+ """Validate edit tree.
+
+ obj (Dict[str, Any]): JSON-serializable data to validate.
+ RETURNS (List[str]): A list of error messages, if available.
+ """
+ try:
+ EditTreeSchema.parse_obj(obj)
+ return []
+ except ValidationError as e:
+ errors = e.errors()
+ data = defaultdict(list)
+ for error in errors:
+ err_loc = " -> ".join([str(p) for p in error.get("loc", [])])
+ data[err_loc].append(error.get("msg"))
+ return [f"[{loc}] {', '.join(msg)}" for loc, msg in data.items()] # type: ignore[arg-type]
diff --git a/spacy/pipeline/_parser_internals/arc_eager.pyx b/spacy/pipeline/_parser_internals/arc_eager.pyx
index 029e2e29e..257b5ef8a 100644
--- a/spacy/pipeline/_parser_internals/arc_eager.pyx
+++ b/spacy/pipeline/_parser_internals/arc_eager.pyx
@@ -10,6 +10,7 @@ from ...strings cimport hash_string
from ...structs cimport TokenC
from ...tokens.doc cimport Doc, set_children_from_heads
from ...tokens.token cimport MISSING_DEP
+from ...training import split_bilu_label
from ...training.example cimport Example
from .stateclass cimport StateClass
from ._state cimport StateC, ArcC
@@ -218,7 +219,7 @@ def _get_aligned_sent_starts(example):
sent_starts = [False] * len(example.x)
seen_words = set()
for y_sent in example.y.sents:
- x_indices = list(align[y_sent.start : y_sent.end].dataXd)
+ x_indices = list(align[y_sent.start : y_sent.end])
if any(x_idx in seen_words for x_idx in x_indices):
# If there are any tokens in X that align across two sentences,
# regard the sentence annotations as missing, as we can't
@@ -687,7 +688,7 @@ cdef class ArcEager(TransitionSystem):
return self.c[name_or_id]
name = name_or_id
if '-' in name:
- move_str, label_str = name.split('-', 1)
+ move_str, label_str = split_bilu_label(name)
label = self.strings[label_str]
else:
move_str = name
@@ -824,7 +825,7 @@ cdef class ArcEager(TransitionSystem):
for i in range(self.n_moves):
print(self.get_class_name(i), is_valid[i], costs[i])
print("Gold sent starts?", is_sent_start(&gold_state, state.B(0)), is_sent_start(&gold_state, state.B(1)))
- raise ValueError("Could not find gold transition - see logs above.")
+ raise ValueError(Errors.E1031)
def get_oracle_sequence_from_state(self, StateClass state, ArcEagerGold gold, _debug=None):
cdef int i
diff --git a/spacy/pipeline/_parser_internals/ner.pyx b/spacy/pipeline/_parser_internals/ner.pyx
index 3edeff19a..fab872f00 100644
--- a/spacy/pipeline/_parser_internals/ner.pyx
+++ b/spacy/pipeline/_parser_internals/ner.pyx
@@ -13,6 +13,7 @@ from ...typedefs cimport weight_t, attr_t
from ...lexeme cimport Lexeme
from ...attrs cimport IS_SPACE
from ...structs cimport TokenC, SpanC
+from ...training import split_bilu_label
from ...training.example cimport Example
from .stateclass cimport StateClass
from ._state cimport StateC
@@ -182,7 +183,7 @@ cdef class BiluoPushDown(TransitionSystem):
if name == '-' or name == '' or name is None:
return Transition(clas=0, move=MISSING, label=0, score=0)
elif '-' in name:
- move_str, label_str = name.split('-', 1)
+ move_str, label_str = split_bilu_label(name)
# Deprecated, hacky way to denote 'not this entity'
if label_str.startswith('!'):
raise ValueError(Errors.E869.format(label=name))
diff --git a/spacy/pipeline/_parser_internals/nonproj.hh b/spacy/pipeline/_parser_internals/nonproj.hh
new file mode 100644
index 000000000..071fd57b4
--- /dev/null
+++ b/spacy/pipeline/_parser_internals/nonproj.hh
@@ -0,0 +1,11 @@
+#ifndef NONPROJ_HH
+#define NONPROJ_HH
+
+#include
+#include
+
+void raise_domain_error(std::string const &msg) {
+ throw std::domain_error(msg);
+}
+
+#endif // NONPROJ_HH
diff --git a/spacy/pipeline/_parser_internals/nonproj.pxd b/spacy/pipeline/_parser_internals/nonproj.pxd
index e69de29bb..aabdf7ebe 100644
--- a/spacy/pipeline/_parser_internals/nonproj.pxd
+++ b/spacy/pipeline/_parser_internals/nonproj.pxd
@@ -0,0 +1,4 @@
+from libcpp.string cimport string
+
+cdef extern from "nonproj.hh":
+ cdef void raise_domain_error(const string& msg) nogil except +
diff --git a/spacy/pipeline/_parser_internals/nonproj.pyx b/spacy/pipeline/_parser_internals/nonproj.pyx
index 36163fcc3..d1b6e7066 100644
--- a/spacy/pipeline/_parser_internals/nonproj.pyx
+++ b/spacy/pipeline/_parser_internals/nonproj.pyx
@@ -4,10 +4,13 @@ for doing pseudo-projective parsing implementation uses the HEAD decoration
scheme.
"""
from copy import copy
+from cython.operator cimport preincrement as incr, dereference as deref
from libc.limits cimport INT_MAX
from libc.stdlib cimport abs
from libcpp cimport bool
+from libcpp.string cimport string, to_string
from libcpp.vector cimport vector
+from libcpp.unordered_set cimport unordered_set
from ...tokens.doc cimport Doc, set_children_from_heads
@@ -49,7 +52,7 @@ def is_nonproj_arc(tokenid, heads):
return _is_nonproj_arc(tokenid, c_heads)
-cdef bool _is_nonproj_arc(int tokenid, const vector[int]& heads) nogil:
+cdef bool _is_nonproj_arc(int tokenid, const vector[int]& heads) nogil except *:
# definition (e.g. Havelka 2007): an arc h -> d, h < d is non-projective
# if there is a token k, h < k < d such that h is not
# an ancestor of k. Same for h -> d, h > d
@@ -58,32 +61,56 @@ cdef bool _is_nonproj_arc(int tokenid, const vector[int]& heads) nogil:
return False
elif head < 0: # unattached tokens cannot be non-projective
return False
-
+
cdef int start, end
if head < tokenid:
start, end = (head+1, tokenid)
else:
start, end = (tokenid+1, head)
for k in range(start, end):
- if _has_head_as_ancestor(k, head, heads):
- continue
- else: # head not in ancestors: d -> h is non-projective
+ if not _has_head_as_ancestor(k, head, heads):
return True
return False
-cdef bool _has_head_as_ancestor(int tokenid, int head, const vector[int]& heads) nogil:
+cdef bool _has_head_as_ancestor(int tokenid, int head, const vector[int]& heads) nogil except *:
ancestor = tokenid
- cnt = 0
- while cnt < heads.size():
+ cdef unordered_set[int] seen_tokens
+ seen_tokens.insert(ancestor)
+ while True:
+ # Reached the head or a disconnected node
if heads[ancestor] == head or heads[ancestor] < 0:
return True
+ # Reached the root
+ if heads[ancestor] == ancestor:
+ return False
ancestor = heads[ancestor]
- cnt += 1
+ result = seen_tokens.insert(ancestor)
+ # Found cycle
+ if not result.second:
+ raise_domain_error(heads_to_string(heads))
return False
+cdef string heads_to_string(const vector[int]& heads) nogil:
+ cdef vector[int].const_iterator citer
+ cdef string cycle_str
+
+ cycle_str.append("Found cycle in dependency graph: [")
+
+ # FIXME: Rewrite using ostringstream when available in Cython.
+ citer = heads.const_begin()
+ while citer != heads.const_end():
+ if citer != heads.const_begin():
+ cycle_str.append(", ")
+ cycle_str.append(to_string(deref(citer)))
+ incr(citer)
+ cycle_str.append("]")
+
+ return cycle_str
+
+
def is_nonproj_tree(heads):
cdef vector[int] c_heads = _heads_to_c(heads)
# a tree is non-projective if at least one arc is non-projective
@@ -176,11 +203,12 @@ def get_smallest_nonproj_arc_slow(heads):
return _get_smallest_nonproj_arc(c_heads)
-cdef int _get_smallest_nonproj_arc(const vector[int]& heads) nogil:
+cdef int _get_smallest_nonproj_arc(const vector[int]& heads) nogil except -2:
# return the smallest non-proj arc or None
# where size is defined as the distance between dep and head
# and ties are broken left to right
cdef int smallest_size = INT_MAX
+ # -1 means its already projective.
cdef int smallest_np_arc = -1
cdef int size
cdef int tokenid
diff --git a/spacy/pipeline/dep_parser.pyx b/spacy/pipeline/dep_parser.pyx
index 50c57ee5b..e5f686158 100644
--- a/spacy/pipeline/dep_parser.pyx
+++ b/spacy/pipeline/dep_parser.pyx
@@ -12,6 +12,7 @@ from ..language import Language
from ._parser_internals import nonproj
from ._parser_internals.nonproj import DELIMITER
from ..scorer import Scorer
+from ..training import remove_bilu_prefix
from ..util import registry
@@ -314,7 +315,7 @@ cdef class DependencyParser(Parser):
# Get the labels from the model by looking at the available moves
for move in self.move_names:
if "-" in move:
- label = move.split("-")[1]
+ label = remove_bilu_prefix(move)
if DELIMITER in label:
label = label.split(DELIMITER)[1]
labels.add(label)
diff --git a/spacy/pipeline/edit_tree_lemmatizer.py b/spacy/pipeline/edit_tree_lemmatizer.py
new file mode 100644
index 000000000..332badd8c
--- /dev/null
+++ b/spacy/pipeline/edit_tree_lemmatizer.py
@@ -0,0 +1,425 @@
+from typing import cast, Any, Callable, Dict, Iterable, List, Optional
+from typing import Tuple
+from collections import Counter
+from itertools import islice
+import numpy as np
+
+import srsly
+from thinc.api import Config, Model, SequenceCategoricalCrossentropy, NumpyOps
+from thinc.types import Floats2d, Ints2d
+
+from ._edit_tree_internals.edit_trees import EditTrees
+from ._edit_tree_internals.schemas import validate_edit_tree
+from .lemmatizer import lemmatizer_score
+from .trainable_pipe import TrainablePipe
+from ..errors import Errors
+from ..language import Language
+from ..tokens import Doc
+from ..training import Example, validate_examples, validate_get_examples
+from ..vocab import Vocab
+from .. import util
+
+
+# The cutoff value of *top_k* above which an alternative method is used to process guesses.
+TOP_K_GUARDRAIL = 20
+
+
+default_model_config = """
+[model]
+@architectures = "spacy.Tagger.v2"
+
+[model.tok2vec]
+@architectures = "spacy.HashEmbedCNN.v2"
+pretrained_vectors = null
+width = 96
+depth = 4
+embed_size = 2000
+window_size = 1
+maxout_pieces = 3
+subword_features = true
+"""
+DEFAULT_EDIT_TREE_LEMMATIZER_MODEL = Config().from_str(default_model_config)["model"]
+
+
+@Language.factory(
+ "trainable_lemmatizer",
+ assigns=["token.lemma"],
+ requires=[],
+ default_config={
+ "model": DEFAULT_EDIT_TREE_LEMMATIZER_MODEL,
+ "backoff": "orth",
+ "min_tree_freq": 3,
+ "overwrite": False,
+ "top_k": 1,
+ "scorer": {"@scorers": "spacy.lemmatizer_scorer.v1"},
+ },
+ default_score_weights={"lemma_acc": 1.0},
+)
+def make_edit_tree_lemmatizer(
+ nlp: Language,
+ name: str,
+ model: Model,
+ backoff: Optional[str],
+ min_tree_freq: int,
+ overwrite: bool,
+ top_k: int,
+ scorer: Optional[Callable],
+):
+ """Construct an EditTreeLemmatizer component."""
+ return EditTreeLemmatizer(
+ nlp.vocab,
+ model,
+ name,
+ backoff=backoff,
+ min_tree_freq=min_tree_freq,
+ overwrite=overwrite,
+ top_k=top_k,
+ scorer=scorer,
+ )
+
+
+class EditTreeLemmatizer(TrainablePipe):
+ """
+ Lemmatizer that lemmatizes each word using a predicted edit tree.
+ """
+
+ def __init__(
+ self,
+ vocab: Vocab,
+ model: Model,
+ name: str = "trainable_lemmatizer",
+ *,
+ backoff: Optional[str] = "orth",
+ min_tree_freq: int = 3,
+ overwrite: bool = False,
+ top_k: int = 1,
+ scorer: Optional[Callable] = lemmatizer_score,
+ ):
+ """
+ Construct an edit tree lemmatizer.
+
+ backoff (Optional[str]): backoff to use when the predicted edit trees
+ are not applicable. Must be an attribute of Token or None (leave the
+ lemma unset).
+ min_tree_freq (int): prune trees that are applied less than this
+ frequency in the training data.
+ overwrite (bool): overwrite existing lemma annotations.
+ top_k (int): try to apply at most the k most probable edit trees.
+ """
+ self.vocab = vocab
+ self.model = model
+ self.name = name
+ self.backoff = backoff
+ self.min_tree_freq = min_tree_freq
+ self.overwrite = overwrite
+ self.top_k = top_k
+
+ self.trees = EditTrees(self.vocab.strings)
+ self.tree2label: Dict[int, int] = {}
+
+ self.cfg: Dict[str, Any] = {"labels": []}
+ self.scorer = scorer
+ self.numpy_ops = NumpyOps()
+
+ def get_loss(
+ self, examples: Iterable[Example], scores: List[Floats2d]
+ ) -> Tuple[float, List[Floats2d]]:
+ validate_examples(examples, "EditTreeLemmatizer.get_loss")
+ loss_func = SequenceCategoricalCrossentropy(normalize=False, missing_value=-1)
+
+ truths = []
+ for eg in examples:
+ eg_truths = []
+ for (predicted, gold_lemma) in zip(
+ eg.predicted, eg.get_aligned("LEMMA", as_string=True)
+ ):
+ if gold_lemma is None or gold_lemma == "":
+ label = -1
+ else:
+ tree_id = self.trees.add(predicted.text, gold_lemma)
+ label = self.tree2label.get(tree_id, 0)
+ eg_truths.append(label)
+
+ truths.append(eg_truths)
+
+ d_scores, loss = loss_func(scores, truths)
+ if self.model.ops.xp.isnan(loss):
+ raise ValueError(Errors.E910.format(name=self.name))
+
+ return float(loss), d_scores
+
+ def predict(self, docs: Iterable[Doc]) -> List[Ints2d]:
+ if self.top_k == 1:
+ scores2guesses = self._scores2guesses_top_k_equals_1
+ elif self.top_k <= TOP_K_GUARDRAIL:
+ scores2guesses = self._scores2guesses_top_k_greater_1
+ else:
+ scores2guesses = self._scores2guesses_top_k_guardrail
+ # The behaviour of *_scores2guesses_top_k_greater_1()* is efficient for values
+ # of *top_k>1* that are likely to be useful when the edit tree lemmatizer is used
+ # for its principal purpose of lemmatizing tokens. However, the code could also
+ # be used for other purposes, and with very large values of *top_k* the method
+ # becomes inefficient. In such cases, *_scores2guesses_top_k_guardrail()* is used
+ # instead.
+ n_docs = len(list(docs))
+ if not any(len(doc) for doc in docs):
+ # Handle cases where there are no tokens in any docs.
+ n_labels = len(self.cfg["labels"])
+ guesses: List[Ints2d] = [self.model.ops.alloc2i(0, n_labels) for _ in docs]
+ assert len(guesses) == n_docs
+ return guesses
+ scores = self.model.predict(docs)
+ assert len(scores) == n_docs
+ guesses = scores2guesses(docs, scores)
+ assert len(guesses) == n_docs
+ return guesses
+
+ def _scores2guesses_top_k_equals_1(self, docs, scores):
+ guesses = []
+ for doc, doc_scores in zip(docs, scores):
+ doc_guesses = doc_scores.argmax(axis=1)
+ doc_guesses = self.numpy_ops.asarray(doc_guesses)
+
+ doc_compat_guesses = []
+ for i, token in enumerate(doc):
+ tree_id = self.cfg["labels"][doc_guesses[i]]
+ if self.trees.apply(tree_id, token.text) is not None:
+ doc_compat_guesses.append(tree_id)
+ else:
+ doc_compat_guesses.append(-1)
+ guesses.append(np.array(doc_compat_guesses))
+
+ return guesses
+
+ def _scores2guesses_top_k_greater_1(self, docs, scores):
+ guesses = []
+ top_k = min(self.top_k, len(self.labels))
+ for doc, doc_scores in zip(docs, scores):
+ doc_scores = self.numpy_ops.asarray(doc_scores)
+ doc_compat_guesses = []
+ for i, token in enumerate(doc):
+ for _ in range(top_k):
+ candidate = int(doc_scores[i].argmax())
+ candidate_tree_id = self.cfg["labels"][candidate]
+ if self.trees.apply(candidate_tree_id, token.text) is not None:
+ doc_compat_guesses.append(candidate_tree_id)
+ break
+ doc_scores[i, candidate] = np.finfo(np.float32).min
+ else:
+ doc_compat_guesses.append(-1)
+ guesses.append(np.array(doc_compat_guesses))
+
+ return guesses
+
+ def _scores2guesses_top_k_guardrail(self, docs, scores):
+ guesses = []
+ for doc, doc_scores in zip(docs, scores):
+ doc_guesses = np.argsort(doc_scores)[..., : -self.top_k - 1 : -1]
+ doc_guesses = self.numpy_ops.asarray(doc_guesses)
+
+ doc_compat_guesses = []
+ for token, candidates in zip(doc, doc_guesses):
+ tree_id = -1
+ for candidate in candidates:
+ candidate_tree_id = self.cfg["labels"][candidate]
+
+ if self.trees.apply(candidate_tree_id, token.text) is not None:
+ tree_id = candidate_tree_id
+ break
+ doc_compat_guesses.append(tree_id)
+
+ guesses.append(np.array(doc_compat_guesses))
+
+ return guesses
+
+ def set_annotations(self, docs: Iterable[Doc], batch_tree_ids):
+ for i, doc in enumerate(docs):
+ doc_tree_ids = batch_tree_ids[i]
+ if hasattr(doc_tree_ids, "get"):
+ doc_tree_ids = doc_tree_ids.get()
+ for j, tree_id in enumerate(doc_tree_ids):
+ if self.overwrite or doc[j].lemma == 0:
+ # If no applicable tree could be found during prediction,
+ # the special identifier -1 is used. Otherwise the tree
+ # is guaranteed to be applicable.
+ if tree_id == -1:
+ if self.backoff is not None:
+ doc[j].lemma = getattr(doc[j], self.backoff)
+ else:
+ lemma = self.trees.apply(tree_id, doc[j].text)
+ doc[j].lemma_ = lemma
+
+ @property
+ def labels(self) -> Tuple[int, ...]:
+ """Returns the labels currently added to the component."""
+ return tuple(self.cfg["labels"])
+
+ @property
+ def hide_labels(self) -> bool:
+ return True
+
+ @property
+ def label_data(self) -> Dict:
+ trees = []
+ for tree_id in range(len(self.trees)):
+ tree = self.trees[tree_id]
+ if "orig" in tree:
+ tree["orig"] = self.vocab.strings[tree["orig"]]
+ if "subst" in tree:
+ tree["subst"] = self.vocab.strings[tree["subst"]]
+ trees.append(tree)
+ return dict(trees=trees, labels=tuple(self.cfg["labels"]))
+
+ def initialize(
+ self,
+ get_examples: Callable[[], Iterable[Example]],
+ *,
+ nlp: Optional[Language] = None,
+ labels: Optional[Dict] = None,
+ ):
+ validate_get_examples(get_examples, "EditTreeLemmatizer.initialize")
+
+ if labels is None:
+ self._labels_from_data(get_examples)
+ else:
+ self._add_labels(labels)
+
+ # Sample for the model.
+ doc_sample = []
+ label_sample = []
+ for example in islice(get_examples(), 10):
+ doc_sample.append(example.x)
+ gold_labels: List[List[float]] = []
+ for token in example.reference:
+ if token.lemma == 0:
+ gold_label = None
+ else:
+ gold_label = self._pair2label(token.text, token.lemma_)
+
+ gold_labels.append(
+ [
+ 1.0 if label == gold_label else 0.0
+ for label in self.cfg["labels"]
+ ]
+ )
+
+ gold_labels = cast(Floats2d, gold_labels)
+ label_sample.append(self.model.ops.asarray(gold_labels, dtype="float32"))
+
+ self._require_labels()
+ assert len(doc_sample) > 0, Errors.E923.format(name=self.name)
+ assert len(label_sample) > 0, Errors.E923.format(name=self.name)
+
+ self.model.initialize(X=doc_sample, Y=label_sample)
+
+ def from_bytes(self, bytes_data, *, exclude=tuple()):
+ deserializers = {
+ "cfg": lambda b: self.cfg.update(srsly.json_loads(b)),
+ "model": lambda b: self.model.from_bytes(b),
+ "vocab": lambda b: self.vocab.from_bytes(b, exclude=exclude),
+ "trees": lambda b: self.trees.from_bytes(b),
+ }
+
+ util.from_bytes(bytes_data, deserializers, exclude)
+
+ return self
+
+ def to_bytes(self, *, exclude=tuple()):
+ serializers = {
+ "cfg": lambda: srsly.json_dumps(self.cfg),
+ "model": lambda: self.model.to_bytes(),
+ "vocab": lambda: self.vocab.to_bytes(exclude=exclude),
+ "trees": lambda: self.trees.to_bytes(),
+ }
+
+ return util.to_bytes(serializers, exclude)
+
+ def to_disk(self, path, exclude=tuple()):
+ path = util.ensure_path(path)
+ serializers = {
+ "cfg": lambda p: srsly.write_json(p, self.cfg),
+ "model": lambda p: self.model.to_disk(p),
+ "vocab": lambda p: self.vocab.to_disk(p, exclude=exclude),
+ "trees": lambda p: self.trees.to_disk(p),
+ }
+ util.to_disk(path, serializers, exclude)
+
+ def from_disk(self, path, exclude=tuple()):
+ def load_model(p):
+ try:
+ with open(p, "rb") as mfile:
+ self.model.from_bytes(mfile.read())
+ except AttributeError:
+ raise ValueError(Errors.E149) from None
+
+ deserializers = {
+ "cfg": lambda p: self.cfg.update(srsly.read_json(p)),
+ "model": load_model,
+ "vocab": lambda p: self.vocab.from_disk(p, exclude=exclude),
+ "trees": lambda p: self.trees.from_disk(p),
+ }
+
+ util.from_disk(path, deserializers, exclude)
+ return self
+
+ def _add_labels(self, labels: Dict):
+ if "labels" not in labels:
+ raise ValueError(Errors.E857.format(name="labels"))
+ if "trees" not in labels:
+ raise ValueError(Errors.E857.format(name="trees"))
+
+ self.cfg["labels"] = list(labels["labels"])
+ trees = []
+ for tree in labels["trees"]:
+ errors = validate_edit_tree(tree)
+ if errors:
+ raise ValueError(Errors.E1026.format(errors="\n".join(errors)))
+
+ tree = dict(tree)
+ if "orig" in tree:
+ tree["orig"] = self.vocab.strings.add(tree["orig"])
+ if "orig" in tree:
+ tree["subst"] = self.vocab.strings.add(tree["subst"])
+
+ trees.append(tree)
+
+ self.trees.from_json(trees)
+
+ for label, tree in enumerate(self.labels):
+ self.tree2label[tree] = label
+
+ def _labels_from_data(self, get_examples: Callable[[], Iterable[Example]]):
+ # Count corpus tree frequencies in ad-hoc storage to avoid cluttering
+ # the final pipe/string store.
+ vocab = Vocab()
+ trees = EditTrees(vocab.strings)
+ tree_freqs: Counter = Counter()
+ repr_pairs: Dict = {}
+ for example in get_examples():
+ for token in example.reference:
+ if token.lemma != 0:
+ tree_id = trees.add(token.text, token.lemma_)
+ tree_freqs[tree_id] += 1
+ repr_pairs[tree_id] = (token.text, token.lemma_)
+
+ # Construct trees that make the frequency cut-off using representative
+ # form - token pairs.
+ for tree_id, freq in tree_freqs.items():
+ if freq >= self.min_tree_freq:
+ form, lemma = repr_pairs[tree_id]
+ self._pair2label(form, lemma, add_label=True)
+
+ def _pair2label(self, form, lemma, add_label=False):
+ """
+ Look up the edit tree identifier for a form/label pair. If the edit
+ tree is unknown and "add_label" is set, the edit tree will be added to
+ the labels.
+ """
+ tree_id = self.trees.add(form, lemma)
+ if tree_id not in self.tree2label:
+ if not add_label:
+ return None
+
+ self.tree2label[tree_id] = len(self.cfg["labels"])
+ self.cfg["labels"].append(tree_id)
+ return self.tree2label[tree_id]
diff --git a/spacy/pipeline/entity_linker.py b/spacy/pipeline/entity_linker.py
index 1169e898d..62845287b 100644
--- a/spacy/pipeline/entity_linker.py
+++ b/spacy/pipeline/entity_linker.py
@@ -6,17 +6,17 @@ import srsly
import random
from thinc.api import CosineDistance, Model, Optimizer, Config
from thinc.api import set_dropout_rate
-import warnings
from ..kb import KnowledgeBase, Candidate
from ..ml import empty_kb
from ..tokens import Doc, Span
from .pipe import deserialize_config
+from .legacy.entity_linker import EntityLinker_v1
from .trainable_pipe import TrainablePipe
from ..language import Language
from ..vocab import Vocab
from ..training import Example, validate_examples, validate_get_examples
-from ..errors import Errors, Warnings
+from ..errors import Errors
from ..util import SimpleFrozenList, registry
from .. import util
from ..scorer import Scorer
@@ -26,7 +26,7 @@ BACKWARD_OVERWRITE = True
default_model_config = """
[model]
-@architectures = "spacy.EntityLinker.v1"
+@architectures = "spacy.EntityLinker.v2"
[model.tok2vec]
@architectures = "spacy.HashEmbedCNN.v2"
@@ -53,8 +53,12 @@ DEFAULT_NEL_MODEL = Config().from_str(default_model_config)["model"]
"incl_context": True,
"entity_vector_length": 64,
"get_candidates": {"@misc": "spacy.CandidateGenerator.v1"},
+ "get_candidates_batch": {"@misc": "spacy.CandidateBatchGenerator.v1"},
"overwrite": True,
"scorer": {"@scorers": "spacy.entity_linker_scorer.v1"},
+ "use_gold_ents": True,
+ "candidates_batch_size": 1,
+ "threshold": None,
},
default_score_weights={
"nel_micro_f": 1.0,
@@ -73,8 +77,14 @@ def make_entity_linker(
incl_context: bool,
entity_vector_length: int,
get_candidates: Callable[[KnowledgeBase, Span], Iterable[Candidate]],
+ get_candidates_batch: Callable[
+ [KnowledgeBase, Iterable[Span]], Iterable[Iterable[Candidate]]
+ ],
overwrite: bool,
scorer: Optional[Callable],
+ use_gold_ents: bool,
+ candidates_batch_size: int,
+ threshold: Optional[float] = None,
):
"""Construct an EntityLinker component.
@@ -86,10 +96,34 @@ def make_entity_linker(
incl_prior (bool): Whether or not to include prior probabilities from the KB in the model.
incl_context (bool): Whether or not to include the local context in the model.
entity_vector_length (int): Size of encoding vectors in the KB.
- get_candidates (Callable[[KnowledgeBase, "Span"], Iterable[Candidate]]): Function that
+ get_candidates (Callable[[KnowledgeBase, Span], Iterable[Candidate]]): Function that
produces a list of candidates, given a certain knowledge base and a textual mention.
+ get_candidates_batch (
+ Callable[[KnowledgeBase, Iterable[Span]], Iterable[Iterable[Candidate]]], Iterable[Candidate]]
+ ): Function that produces a list of candidates, given a certain knowledge base and several textual mentions.
scorer (Optional[Callable]): The scoring method.
+ use_gold_ents (bool): Whether to copy entities from gold docs or not. If false, another
+ component must provide entity annotations.
+ candidates_batch_size (int): Size of batches for entity candidate generation.
+ threshold (Optional[float]): Confidence threshold for entity predictions. If confidence is below the threshold,
+ prediction is discarded. If None, predictions are not filtered by any threshold.
"""
+
+ if not model.attrs.get("include_span_maker", False):
+ # The only difference in arguments here is that use_gold_ents and threshold aren't available.
+ return EntityLinker_v1(
+ nlp.vocab,
+ model,
+ name,
+ labels_discard=labels_discard,
+ n_sents=n_sents,
+ incl_prior=incl_prior,
+ incl_context=incl_context,
+ entity_vector_length=entity_vector_length,
+ get_candidates=get_candidates,
+ overwrite=overwrite,
+ scorer=scorer,
+ )
return EntityLinker(
nlp.vocab,
model,
@@ -100,8 +134,12 @@ def make_entity_linker(
incl_context=incl_context,
entity_vector_length=entity_vector_length,
get_candidates=get_candidates,
+ get_candidates_batch=get_candidates_batch,
overwrite=overwrite,
scorer=scorer,
+ use_gold_ents=use_gold_ents,
+ candidates_batch_size=candidates_batch_size,
+ threshold=threshold,
)
@@ -134,8 +172,14 @@ class EntityLinker(TrainablePipe):
incl_context: bool,
entity_vector_length: int,
get_candidates: Callable[[KnowledgeBase, Span], Iterable[Candidate]],
+ get_candidates_batch: Callable[
+ [KnowledgeBase, Iterable[Span]], Iterable[Iterable[Candidate]]
+ ],
overwrite: bool = BACKWARD_OVERWRITE,
scorer: Optional[Callable] = entity_linker_score,
+ use_gold_ents: bool,
+ candidates_batch_size: int,
+ threshold: Optional[float] = None,
) -> None:
"""Initialize an entity linker.
@@ -150,11 +194,28 @@ class EntityLinker(TrainablePipe):
entity_vector_length (int): Size of encoding vectors in the KB.
get_candidates (Callable[[KnowledgeBase, Span], Iterable[Candidate]]): Function that
produces a list of candidates, given a certain knowledge base and a textual mention.
- scorer (Optional[Callable]): The scoring method. Defaults to
- Scorer.score_links.
-
+ get_candidates_batch (
+ Callable[[KnowledgeBase, Iterable[Span]], Iterable[Iterable[Candidate]]],
+ Iterable[Candidate]]
+ ): Function that produces a list of candidates, given a certain knowledge base and several textual mentions.
+ scorer (Optional[Callable]): The scoring method. Defaults to Scorer.score_links.
+ use_gold_ents (bool): Whether to copy entities from gold docs or not. If false, another
+ component must provide entity annotations.
+ candidates_batch_size (int): Size of batches for entity candidate generation.
+ threshold (Optional[float]): Confidence threshold for entity predictions. If confidence is below the
+ threshold, prediction is discarded. If None, predictions are not filtered by any threshold.
DOCS: https://spacy.io/api/entitylinker#init
"""
+
+ if threshold is not None and not (0 <= threshold <= 1):
+ raise ValueError(
+ Errors.E1043.format(
+ range_start=0,
+ range_end=1,
+ value=threshold,
+ )
+ )
+
self.vocab = vocab
self.model = model
self.name = name
@@ -163,12 +224,19 @@ class EntityLinker(TrainablePipe):
self.incl_prior = incl_prior
self.incl_context = incl_context
self.get_candidates = get_candidates
+ self.get_candidates_batch = get_candidates_batch
self.cfg: Dict[str, Any] = {"overwrite": overwrite}
self.distance = CosineDistance(normalize=False)
# how many neighbour sentences to take into account
- # create an empty KB by default. If you want to load a predefined one, specify it in 'initialize'.
+ # create an empty KB by default
self.kb = empty_kb(entity_vector_length)(self.vocab)
self.scorer = scorer
+ self.use_gold_ents = use_gold_ents
+ self.candidates_batch_size = candidates_batch_size
+ self.threshold = threshold
+
+ if candidates_batch_size < 1:
+ raise ValueError(Errors.E1044)
def set_kb(self, kb_loader: Callable[[Vocab], KnowledgeBase]):
"""Define the KB of this pipe by providing a function that will
@@ -176,7 +244,7 @@ class EntityLinker(TrainablePipe):
if not callable(kb_loader):
raise ValueError(Errors.E885.format(arg_type=type(kb_loader)))
- self.kb = kb_loader(self.vocab)
+ self.kb = kb_loader(self.vocab) # type: ignore
def validate_kb(self) -> None:
# Raise an error if the knowledge base is not initialized.
@@ -198,8 +266,8 @@ class EntityLinker(TrainablePipe):
get_examples (Callable[[], Iterable[Example]]): Function that
returns a representative sample of gold-standard Example objects.
nlp (Language): The current nlp object the component is part of.
- kb_loader (Callable[[Vocab], KnowledgeBase]): A function that creates a KnowledgeBase from a Vocab instance.
- Note that providing this argument, will overwrite all data accumulated in the current KB.
+ kb_loader (Callable[[Vocab], KnowledgeBase]): A function that creates a KnowledgeBase from a Vocab
+ instance. Note that providing this argument will overwrite all data accumulated in the current KB.
Use this only when loading a KB as-such from file.
DOCS: https://spacy.io/api/entitylinker#initialize
@@ -211,15 +279,50 @@ class EntityLinker(TrainablePipe):
nO = self.kb.entity_vector_length
doc_sample = []
vector_sample = []
- for example in islice(get_examples(), 10):
- doc_sample.append(example.x)
+ for eg in islice(get_examples(), 10):
+ doc = eg.x
+ if self.use_gold_ents:
+ ents, _ = eg.get_aligned_ents_and_ner()
+ doc.ents = ents
+ doc_sample.append(doc)
vector_sample.append(self.model.ops.alloc1f(nO))
assert len(doc_sample) > 0, Errors.E923.format(name=self.name)
assert len(vector_sample) > 0, Errors.E923.format(name=self.name)
+
+ # XXX In order for size estimation to work, there has to be at least
+ # one entity. It's not used for training so it doesn't have to be real,
+ # so we add a fake one if none are present.
+ # We can't use Doc.has_annotation here because it can be True for docs
+ # that have been through an NER component but got no entities.
+ has_annotations = any([doc.ents for doc in doc_sample])
+ if not has_annotations:
+ doc = doc_sample[0]
+ ent = doc[0:1]
+ ent.label_ = "XXX"
+ doc.ents = (ent,)
+
self.model.initialize(
X=doc_sample, Y=self.model.ops.asarray(vector_sample, dtype="float32")
)
+ if not has_annotations:
+ # Clean up dummy annotation
+ doc.ents = []
+
+ def batch_has_learnable_example(self, examples):
+ """Check if a batch contains a learnable example.
+
+ If one isn't present, then the update step needs to be skipped.
+ """
+
+ for eg in examples:
+ for ent in eg.predicted.ents:
+ candidates = list(self.get_candidates(self.kb, ent))
+ if candidates:
+ return True
+
+ return False
+
def update(
self,
examples: Iterable[Example],
@@ -247,35 +350,30 @@ class EntityLinker(TrainablePipe):
if not examples:
return losses
validate_examples(examples, "EntityLinker.update")
- sentence_docs = []
- for eg in examples:
- sentences = [s for s in eg.reference.sents]
- kb_ids = eg.get_aligned("ENT_KB_ID", as_string=True)
- for ent in eg.reference.ents:
- # KB ID of the first token is the same as the whole span
- kb_id = kb_ids[ent.start]
- if kb_id:
- try:
- # find the sentence in the list of sentences.
- sent_index = sentences.index(ent.sent)
- except AttributeError:
- # Catch the exception when ent.sent is None and provide a user-friendly warning
- raise RuntimeError(Errors.E030) from None
- # get n previous sentences, if there are any
- start_sentence = max(0, sent_index - self.n_sents)
- # get n posterior sentences, or as many < n as there are
- end_sentence = min(len(sentences) - 1, sent_index + self.n_sents)
- # get token positions
- start_token = sentences[start_sentence].start
- end_token = sentences[end_sentence].end
- # append that span as a doc to training
- sent_doc = eg.predicted[start_token:end_token].as_doc()
- sentence_docs.append(sent_doc)
+
set_dropout_rate(self.model, drop)
- if not sentence_docs:
- warnings.warn(Warnings.W093.format(name="Entity Linker"))
+ docs = [eg.predicted for eg in examples]
+ # save to restore later
+ old_ents = [doc.ents for doc in docs]
+
+ for doc, ex in zip(docs, examples):
+ if self.use_gold_ents:
+ ents, _ = ex.get_aligned_ents_and_ner()
+ doc.ents = ents
+ else:
+ # only keep matching ents
+ doc.ents = ex.get_matching_ents()
+
+ # make sure we have something to learn from, if not, short-circuit
+ if not self.batch_has_learnable_example(examples):
return losses
- sentence_encodings, bp_context = self.model.begin_update(sentence_docs)
+
+ sentence_encodings, bp_context = self.model.begin_update(docs)
+
+ # now restore the ents
+ for doc, old in zip(docs, old_ents):
+ doc.ents = old
+
loss, d_scores = self.get_loss(
sentence_encodings=sentence_encodings, examples=examples
)
@@ -288,24 +386,41 @@ class EntityLinker(TrainablePipe):
def get_loss(self, examples: Iterable[Example], sentence_encodings: Floats2d):
validate_examples(examples, "EntityLinker.get_loss")
entity_encodings = []
+ eidx = 0 # indices in gold entities to keep
+ keep_ents = [] # indices in sentence_encodings to keep
+
for eg in examples:
kb_ids = eg.get_aligned("ENT_KB_ID", as_string=True)
- for ent in eg.reference.ents:
+
+ for ent in eg.get_matching_ents():
kb_id = kb_ids[ent.start]
if kb_id:
entity_encoding = self.kb.get_vector(kb_id)
entity_encodings.append(entity_encoding)
- entity_encodings = self.model.ops.asarray(entity_encodings, dtype="float32")
- if sentence_encodings.shape != entity_encodings.shape:
+ keep_ents.append(eidx)
+
+ eidx += 1
+ entity_encodings = self.model.ops.asarray2f(entity_encodings, dtype="float32")
+ selected_encodings = sentence_encodings[keep_ents]
+
+ # if there are no matches, short circuit
+ if not keep_ents:
+ out = self.model.ops.alloc2f(*sentence_encodings.shape)
+ return 0, out
+
+ if selected_encodings.shape != entity_encodings.shape:
err = Errors.E147.format(
method="get_loss", msg="gold entities do not match up"
)
raise RuntimeError(err)
- # TODO: fix typing issue here
- gradients = self.distance.get_grad(sentence_encodings, entity_encodings) # type: ignore
- loss = self.distance.get_loss(sentence_encodings, entity_encodings) # type: ignore
+ gradients = self.distance.get_grad(selected_encodings, entity_encodings)
+ # to match the input size, we need to give a zero gradient for items not in the kb
+ out = self.model.ops.alloc2f(*sentence_encodings.shape)
+ out[keep_ents] = gradients
+
+ loss = self.distance.get_loss(selected_encodings, entity_encodings)
loss = loss / len(entity_encodings)
- return float(loss), gradients
+ return float(loss), out
def predict(self, docs: Iterable[Doc]) -> List[str]:
"""Apply the pipeline's model to a batch of docs, without modifying them.
@@ -320,27 +435,53 @@ class EntityLinker(TrainablePipe):
self.validate_kb()
entity_count = 0
final_kb_ids: List[str] = []
+ xp = self.model.ops.xp
if not docs:
return final_kb_ids
if isinstance(docs, Doc):
docs = [docs]
for i, doc in enumerate(docs):
+ if len(doc) == 0:
+ continue
sentences = [s for s in doc.sents]
- if len(doc) > 0:
- # Looping through each entity (TODO: rewrite)
- for ent in doc.ents:
- sent = ent.sent
- sent_index = sentences.index(sent)
+
+ # Loop over entities in batches.
+ for ent_idx in range(0, len(doc.ents), self.candidates_batch_size):
+ ent_batch = doc.ents[ent_idx : ent_idx + self.candidates_batch_size]
+
+ # Look up candidate entities.
+ valid_ent_idx = [
+ idx
+ for idx in range(len(ent_batch))
+ if ent_batch[idx].label_ not in self.labels_discard
+ ]
+
+ batch_candidates = list(
+ self.get_candidates_batch(
+ self.kb, [ent_batch[idx] for idx in valid_ent_idx]
+ )
+ if self.candidates_batch_size > 1
+ else [
+ self.get_candidates(self.kb, ent_batch[idx])
+ for idx in valid_ent_idx
+ ]
+ )
+
+ # Looping through each entity in batch (TODO: rewrite)
+ for j, ent in enumerate(ent_batch):
+ sent_index = sentences.index(ent.sent)
assert sent_index >= 0
- # get n_neighbour sentences, clipped to the length of the document
- start_sentence = max(0, sent_index - self.n_sents)
- end_sentence = min(len(sentences) - 1, sent_index + self.n_sents)
- start_token = sentences[start_sentence].start
- end_token = sentences[end_sentence].end
- sent_doc = doc[start_token:end_token].as_doc()
- # currently, the context is the same for each entity in a sentence (should be refined)
- xp = self.model.ops.xp
+
if self.incl_context:
+ # get n_neighbour sentences, clipped to the length of the document
+ start_sentence = max(0, sent_index - self.n_sents)
+ end_sentence = min(
+ len(sentences) - 1, sent_index + self.n_sents
+ )
+ start_token = sentences[start_sentence].start
+ end_token = sentences[end_sentence].end
+ sent_doc = doc[start_token:end_token].as_doc()
+ # currently, the context is the same for each entity in a sentence (should be refined)
sentence_encoding = self.model.predict([sent_doc])[0]
sentence_encoding_t = sentence_encoding.T
sentence_norm = xp.linalg.norm(sentence_encoding_t)
@@ -349,13 +490,12 @@ class EntityLinker(TrainablePipe):
# ignoring this entity - setting to NIL
final_kb_ids.append(self.NIL)
else:
- candidates = list(self.get_candidates(self.kb, ent))
+ candidates = list(batch_candidates[j])
if not candidates:
# no prediction possible for this entity - setting to NIL
final_kb_ids.append(self.NIL)
- elif len(candidates) == 1:
+ elif len(candidates) == 1 and self.threshold is None:
# shortcut for efficiency reasons: take the 1 candidate
- # TODO: thresholding
final_kb_ids.append(candidates[0].entity_)
else:
random.shuffle(candidates)
@@ -384,10 +524,13 @@ class EntityLinker(TrainablePipe):
if sims.shape != prior_probs.shape:
raise ValueError(Errors.E161)
scores = prior_probs + sims - (prior_probs * sims)
- # TODO: thresholding
- best_index = scores.argmax().item()
- best_candidate = candidates[best_index]
- final_kb_ids.append(best_candidate.entity_)
+ final_kb_ids.append(
+ candidates[scores.argmax().item()].entity_
+ if self.threshold is None
+ or scores.max() >= self.threshold
+ else EntityLinker.NIL
+ )
+
if not (len(final_kb_ids) == entity_count):
err = Errors.E147.format(
method="predict", msg="result variables not of equal length"
diff --git a/spacy/pipeline/entityruler.py b/spacy/pipeline/entityruler.py
index 614d71f41..6a3755533 100644
--- a/spacy/pipeline/entityruler.py
+++ b/spacy/pipeline/entityruler.py
@@ -1,6 +1,5 @@
-import warnings
from typing import Optional, Union, List, Dict, Tuple, Iterable, Any, Callable, Sequence
-from typing import cast
+import warnings
from collections import defaultdict
from pathlib import Path
import srsly
@@ -12,6 +11,7 @@ from ..errors import Errors, Warnings
from ..util import ensure_path, to_disk, from_disk, SimpleFrozenList, registry
from ..tokens import Doc, Span
from ..matcher import Matcher, PhraseMatcher
+from ..matcher.levenshtein import levenshtein_compare
from ..scorer import get_ner_prf
@@ -24,6 +24,7 @@ PatternType = Dict[str, Union[str, List[Dict[str, Any]]]]
assigns=["doc.ents", "token.ent_type", "token.ent_iob"],
default_config={
"phrase_matcher_attr": None,
+ "matcher_fuzzy_compare": {"@misc": "spacy.levenshtein_compare.v1"},
"validate": False,
"overwrite_ents": False,
"ent_id_sep": DEFAULT_ENT_ID_SEP,
@@ -40,6 +41,7 @@ def make_entity_ruler(
nlp: Language,
name: str,
phrase_matcher_attr: Optional[Union[int, str]],
+ matcher_fuzzy_compare: Callable,
validate: bool,
overwrite_ents: bool,
ent_id_sep: str,
@@ -49,6 +51,7 @@ def make_entity_ruler(
nlp,
name,
phrase_matcher_attr=phrase_matcher_attr,
+ matcher_fuzzy_compare=matcher_fuzzy_compare,
validate=validate,
overwrite_ents=overwrite_ents,
ent_id_sep=ent_id_sep,
@@ -82,6 +85,7 @@ class EntityRuler(Pipe):
name: str = "entity_ruler",
*,
phrase_matcher_attr: Optional[Union[int, str]] = None,
+ matcher_fuzzy_compare: Callable = levenshtein_compare,
validate: bool = False,
overwrite_ents: bool = False,
ent_id_sep: str = DEFAULT_ENT_ID_SEP,
@@ -100,7 +104,10 @@ class EntityRuler(Pipe):
added. Used to disable the current entity ruler while creating
phrase patterns with the nlp object.
phrase_matcher_attr (int / str): Token attribute to match on, passed
- to the internal PhraseMatcher as `attr`
+ to the internal PhraseMatcher as `attr`.
+ matcher_fuzzy_compare (Callable): The fuzzy comparison method for the
+ internal Matcher. Defaults to
+ spacy.matcher.levenshtein.levenshtein_compare.
validate (bool): Whether patterns should be validated, passed to
Matcher and PhraseMatcher as `validate`
patterns (iterable): Optional patterns to load in.
@@ -118,7 +125,10 @@ class EntityRuler(Pipe):
self.token_patterns = defaultdict(list) # type: ignore
self.phrase_patterns = defaultdict(list) # type: ignore
self._validate = validate
- self.matcher = Matcher(nlp.vocab, validate=validate)
+ self.matcher_fuzzy_compare = matcher_fuzzy_compare
+ self.matcher = Matcher(
+ nlp.vocab, validate=validate, fuzzy_compare=self.matcher_fuzzy_compare
+ )
self.phrase_matcher_attr = phrase_matcher_attr
self.phrase_matcher = PhraseMatcher(
nlp.vocab, attr=self.phrase_matcher_attr, validate=validate
@@ -159,10 +169,8 @@ class EntityRuler(Pipe):
self._require_patterns()
with warnings.catch_warnings():
warnings.filterwarnings("ignore", message="\\[W036")
- matches = cast(
- List[Tuple[int, int, int]],
- list(self.matcher(doc)) + list(self.phrase_matcher(doc)),
- )
+ matches = list(self.matcher(doc)) + list(self.phrase_matcher(doc))
+
final_matches = set(
[(m_id, start, end) for m_id, start, end in matches if start != end]
)
@@ -182,10 +190,7 @@ class EntityRuler(Pipe):
if start not in seen_tokens and end - 1 not in seen_tokens:
if match_id in self._ent_ids:
label, ent_id = self._ent_ids[match_id]
- span = Span(doc, start, end, label=label)
- if ent_id:
- for token in span:
- token.ent_id_ = ent_id
+ span = Span(doc, start, end, label=label, span_id=ent_id)
else:
span = Span(doc, start, end, label=match_id)
new_entities.append(span)
@@ -322,7 +327,7 @@ class EntityRuler(Pipe):
phrase_pattern["id"] = ent_id
phrase_patterns.append(phrase_pattern)
for entry in token_patterns + phrase_patterns: # type: ignore[operator]
- label = entry["label"]
+ label = entry["label"] # type: ignore
if "id" in entry:
ent_label = label
label = self._create_label(label, entry["id"])
@@ -343,7 +348,11 @@ class EntityRuler(Pipe):
self.token_patterns = defaultdict(list)
self.phrase_patterns = defaultdict(list)
self._ent_ids = defaultdict(tuple)
- self.matcher = Matcher(self.nlp.vocab, validate=self._validate)
+ self.matcher = Matcher(
+ self.nlp.vocab,
+ validate=self._validate,
+ fuzzy_compare=self.matcher_fuzzy_compare,
+ )
self.phrase_matcher = PhraseMatcher(
self.nlp.vocab, attr=self.phrase_matcher_attr, validate=self._validate
)
@@ -359,7 +368,9 @@ class EntityRuler(Pipe):
(label, eid) for (label, eid) in self._ent_ids.values() if eid == ent_id
]
if not label_id_pairs:
- raise ValueError(Errors.E1024.format(ent_id=ent_id))
+ raise ValueError(
+ Errors.E1024.format(attr_type="ID", label=ent_id, component=self.name)
+ )
created_labels = [
self._create_label(label, eid) for (label, eid) in label_id_pairs
]
@@ -435,7 +446,8 @@ class EntityRuler(Pipe):
self.overwrite = cfg.get("overwrite", False)
self.phrase_matcher_attr = cfg.get("phrase_matcher_attr", None)
self.phrase_matcher = PhraseMatcher(
- self.nlp.vocab, attr=self.phrase_matcher_attr
+ self.nlp.vocab,
+ attr=self.phrase_matcher_attr,
)
self.ent_id_sep = cfg.get("ent_id_sep", DEFAULT_ENT_ID_SEP)
else:
diff --git a/spacy/pipeline/legacy/__init__.py b/spacy/pipeline/legacy/__init__.py
new file mode 100644
index 000000000..f216840dc
--- /dev/null
+++ b/spacy/pipeline/legacy/__init__.py
@@ -0,0 +1,3 @@
+from .entity_linker import EntityLinker_v1
+
+__all__ = ["EntityLinker_v1"]
diff --git a/spacy/pipeline/legacy/entity_linker.py b/spacy/pipeline/legacy/entity_linker.py
new file mode 100644
index 000000000..c14dfa1db
--- /dev/null
+++ b/spacy/pipeline/legacy/entity_linker.py
@@ -0,0 +1,422 @@
+# This file is present to provide a prior version of the EntityLinker component
+# for backwards compatability. For details see #9669.
+
+from typing import Optional, Iterable, Callable, Dict, Union, List, Any
+from thinc.types import Floats2d
+from pathlib import Path
+from itertools import islice
+import srsly
+import random
+from thinc.api import CosineDistance, Model, Optimizer
+from thinc.api import set_dropout_rate
+import warnings
+
+from ...kb import KnowledgeBase, Candidate
+from ...ml import empty_kb
+from ...tokens import Doc, Span
+from ..pipe import deserialize_config
+from ..trainable_pipe import TrainablePipe
+from ...language import Language
+from ...vocab import Vocab
+from ...training import Example, validate_examples, validate_get_examples
+from ...errors import Errors, Warnings
+from ...util import SimpleFrozenList
+from ... import util
+from ...scorer import Scorer
+
+# See #9050
+BACKWARD_OVERWRITE = True
+
+
+def entity_linker_score(examples, **kwargs):
+ return Scorer.score_links(examples, negative_labels=[EntityLinker_v1.NIL], **kwargs)
+
+
+class EntityLinker_v1(TrainablePipe):
+ """Pipeline component for named entity linking.
+
+ DOCS: https://spacy.io/api/entitylinker
+ """
+
+ NIL = "NIL" # string used to refer to a non-existing link
+
+ def __init__(
+ self,
+ vocab: Vocab,
+ model: Model,
+ name: str = "entity_linker",
+ *,
+ labels_discard: Iterable[str],
+ n_sents: int,
+ incl_prior: bool,
+ incl_context: bool,
+ entity_vector_length: int,
+ get_candidates: Callable[[KnowledgeBase, Span], Iterable[Candidate]],
+ overwrite: bool = BACKWARD_OVERWRITE,
+ scorer: Optional[Callable] = entity_linker_score,
+ ) -> None:
+ """Initialize an entity linker.
+
+ vocab (Vocab): The shared vocabulary.
+ model (thinc.api.Model): The Thinc Model powering the pipeline component.
+ name (str): The component instance name, used to add entries to the
+ losses during training.
+ labels_discard (Iterable[str]): NER labels that will automatically get a "NIL" prediction.
+ n_sents (int): The number of neighbouring sentences to take into account.
+ incl_prior (bool): Whether or not to include prior probabilities from the KB in the model.
+ incl_context (bool): Whether or not to include the local context in the model.
+ entity_vector_length (int): Size of encoding vectors in the KB.
+ get_candidates (Callable[[KnowledgeBase, Span], Iterable[Candidate]]): Function that
+ produces a list of candidates, given a certain knowledge base and a textual mention.
+ scorer (Optional[Callable]): The scoring method. Defaults to Scorer.score_links.
+ DOCS: https://spacy.io/api/entitylinker#init
+ """
+ self.vocab = vocab
+ self.model = model
+ self.name = name
+ self.labels_discard = list(labels_discard)
+ self.n_sents = n_sents
+ self.incl_prior = incl_prior
+ self.incl_context = incl_context
+ self.get_candidates = get_candidates
+ self.cfg: Dict[str, Any] = {"overwrite": overwrite}
+ self.distance = CosineDistance(normalize=False)
+ # how many neighbour sentences to take into account
+ # create an empty KB by default. If you want to load a predefined one, specify it in 'initialize'.
+ self.kb = empty_kb(entity_vector_length)(self.vocab)
+ self.scorer = scorer
+
+ def set_kb(self, kb_loader: Callable[[Vocab], KnowledgeBase]):
+ """Define the KB of this pipe by providing a function that will
+ create it using this object's vocab."""
+ if not callable(kb_loader):
+ raise ValueError(Errors.E885.format(arg_type=type(kb_loader)))
+
+ self.kb = kb_loader(self.vocab)
+
+ def validate_kb(self) -> None:
+ # Raise an error if the knowledge base is not initialized.
+ if self.kb is None:
+ raise ValueError(Errors.E1018.format(name=self.name))
+ if len(self.kb) == 0:
+ raise ValueError(Errors.E139.format(name=self.name))
+
+ def initialize(
+ self,
+ get_examples: Callable[[], Iterable[Example]],
+ *,
+ nlp: Optional[Language] = None,
+ kb_loader: Optional[Callable[[Vocab], KnowledgeBase]] = None,
+ ):
+ """Initialize the pipe for training, using a representative set
+ of data examples.
+
+ get_examples (Callable[[], Iterable[Example]]): Function that
+ returns a representative sample of gold-standard Example objects.
+ nlp (Language): The current nlp object the component is part of.
+ kb_loader (Callable[[Vocab], KnowledgeBase]): A function that creates an InMemoryLookupKB from a Vocab instance.
+ Note that providing this argument, will overwrite all data accumulated in the current KB.
+ Use this only when loading a KB as-such from file.
+
+ DOCS: https://spacy.io/api/entitylinker#initialize
+ """
+ validate_get_examples(get_examples, "EntityLinker_v1.initialize")
+ if kb_loader is not None:
+ self.set_kb(kb_loader)
+ self.validate_kb()
+ nO = self.kb.entity_vector_length
+ doc_sample = []
+ vector_sample = []
+ for example in islice(get_examples(), 10):
+ doc_sample.append(example.x)
+ vector_sample.append(self.model.ops.alloc1f(nO))
+ assert len(doc_sample) > 0, Errors.E923.format(name=self.name)
+ assert len(vector_sample) > 0, Errors.E923.format(name=self.name)
+ self.model.initialize(
+ X=doc_sample, Y=self.model.ops.asarray(vector_sample, dtype="float32")
+ )
+
+ def update(
+ self,
+ examples: Iterable[Example],
+ *,
+ drop: float = 0.0,
+ sgd: Optional[Optimizer] = None,
+ losses: Optional[Dict[str, float]] = None,
+ ) -> Dict[str, float]:
+ """Learn from a batch of documents and gold-standard information,
+ updating the pipe's model. Delegates to predict and get_loss.
+
+ examples (Iterable[Example]): A batch of Example objects.
+ drop (float): The dropout rate.
+ sgd (thinc.api.Optimizer): The optimizer.
+ losses (Dict[str, float]): Optional record of the loss during training.
+ Updated using the component name as the key.
+ RETURNS (Dict[str, float]): The updated losses dictionary.
+
+ DOCS: https://spacy.io/api/entitylinker#update
+ """
+ self.validate_kb()
+ if losses is None:
+ losses = {}
+ losses.setdefault(self.name, 0.0)
+ if not examples:
+ return losses
+ validate_examples(examples, "EntityLinker_v1.update")
+ sentence_docs = []
+ for eg in examples:
+ sentences = [s for s in eg.reference.sents]
+ kb_ids = eg.get_aligned("ENT_KB_ID", as_string=True)
+ for ent in eg.reference.ents:
+ # KB ID of the first token is the same as the whole span
+ kb_id = kb_ids[ent.start]
+ if kb_id:
+ try:
+ # find the sentence in the list of sentences.
+ sent_index = sentences.index(ent.sent)
+ except AttributeError:
+ # Catch the exception when ent.sent is None and provide a user-friendly warning
+ raise RuntimeError(Errors.E030) from None
+ # get n previous sentences, if there are any
+ start_sentence = max(0, sent_index - self.n_sents)
+ # get n posterior sentences, or as many < n as there are
+ end_sentence = min(len(sentences) - 1, sent_index + self.n_sents)
+ # get token positions
+ start_token = sentences[start_sentence].start
+ end_token = sentences[end_sentence].end
+ # append that span as a doc to training
+ sent_doc = eg.predicted[start_token:end_token].as_doc()
+ sentence_docs.append(sent_doc)
+ set_dropout_rate(self.model, drop)
+ if not sentence_docs:
+ warnings.warn(Warnings.W093.format(name="Entity Linker"))
+ return losses
+ sentence_encodings, bp_context = self.model.begin_update(sentence_docs)
+ loss, d_scores = self.get_loss(
+ sentence_encodings=sentence_encodings, examples=examples
+ )
+ bp_context(d_scores)
+ if sgd is not None:
+ self.finish_update(sgd)
+ losses[self.name] += loss
+ return losses
+
+ def get_loss(self, examples: Iterable[Example], sentence_encodings: Floats2d):
+ validate_examples(examples, "EntityLinker_v1.get_loss")
+ entity_encodings = []
+ for eg in examples:
+ kb_ids = eg.get_aligned("ENT_KB_ID", as_string=True)
+ for ent in eg.reference.ents:
+ kb_id = kb_ids[ent.start]
+ if kb_id:
+ entity_encoding = self.kb.get_vector(kb_id)
+ entity_encodings.append(entity_encoding)
+ entity_encodings = self.model.ops.asarray2f(entity_encodings)
+ if sentence_encodings.shape != entity_encodings.shape:
+ err = Errors.E147.format(
+ method="get_loss", msg="gold entities do not match up"
+ )
+ raise RuntimeError(err)
+ gradients = self.distance.get_grad(sentence_encodings, entity_encodings)
+ loss = self.distance.get_loss(sentence_encodings, entity_encodings)
+ loss = loss / len(entity_encodings)
+ return float(loss), gradients
+
+ def predict(self, docs: Iterable[Doc]) -> List[str]:
+ """Apply the pipeline's model to a batch of docs, without modifying them.
+ Returns the KB IDs for each entity in each doc, including NIL if there is
+ no prediction.
+
+ docs (Iterable[Doc]): The documents to predict.
+ RETURNS (List[str]): The models prediction for each document.
+
+ DOCS: https://spacy.io/api/entitylinker#predict
+ """
+ self.validate_kb()
+ entity_count = 0
+ final_kb_ids: List[str] = []
+ if not docs:
+ return final_kb_ids
+ if isinstance(docs, Doc):
+ docs = [docs]
+ for i, doc in enumerate(docs):
+ sentences = [s for s in doc.sents]
+ if len(doc) > 0:
+ # Looping through each entity (TODO: rewrite)
+ for ent in doc.ents:
+ sent = ent.sent
+ sent_index = sentences.index(sent)
+ assert sent_index >= 0
+ # get n_neighbour sentences, clipped to the length of the document
+ start_sentence = max(0, sent_index - self.n_sents)
+ end_sentence = min(len(sentences) - 1, sent_index + self.n_sents)
+ start_token = sentences[start_sentence].start
+ end_token = sentences[end_sentence].end
+ sent_doc = doc[start_token:end_token].as_doc()
+ # currently, the context is the same for each entity in a sentence (should be refined)
+ xp = self.model.ops.xp
+ if self.incl_context:
+ sentence_encoding = self.model.predict([sent_doc])[0]
+ sentence_encoding_t = sentence_encoding.T
+ sentence_norm = xp.linalg.norm(sentence_encoding_t)
+ entity_count += 1
+ if ent.label_ in self.labels_discard:
+ # ignoring this entity - setting to NIL
+ final_kb_ids.append(self.NIL)
+ else:
+ candidates = list(self.get_candidates(self.kb, ent))
+ if not candidates:
+ # no prediction possible for this entity - setting to NIL
+ final_kb_ids.append(self.NIL)
+ elif len(candidates) == 1:
+ # shortcut for efficiency reasons: take the 1 candidate
+ final_kb_ids.append(candidates[0].entity_)
+ else:
+ random.shuffle(candidates)
+ # set all prior probabilities to 0 if incl_prior=False
+ prior_probs = xp.asarray([c.prior_prob for c in candidates])
+ if not self.incl_prior:
+ prior_probs = xp.asarray([0.0 for _ in candidates])
+ scores = prior_probs
+ # add in similarity from the context
+ if self.incl_context:
+ entity_encodings = xp.asarray(
+ [c.entity_vector for c in candidates]
+ )
+ entity_norm = xp.linalg.norm(entity_encodings, axis=1)
+ if len(entity_encodings) != len(prior_probs):
+ raise RuntimeError(
+ Errors.E147.format(
+ method="predict",
+ msg="vectors not of equal length",
+ )
+ )
+ # cosine similarity
+ sims = xp.dot(entity_encodings, sentence_encoding_t) / (
+ sentence_norm * entity_norm
+ )
+ if sims.shape != prior_probs.shape:
+ raise ValueError(Errors.E161)
+ scores = prior_probs + sims - (prior_probs * sims)
+ best_index = scores.argmax().item()
+ best_candidate = candidates[best_index]
+ final_kb_ids.append(best_candidate.entity_)
+ if not (len(final_kb_ids) == entity_count):
+ err = Errors.E147.format(
+ method="predict", msg="result variables not of equal length"
+ )
+ raise RuntimeError(err)
+ return final_kb_ids
+
+ def set_annotations(self, docs: Iterable[Doc], kb_ids: List[str]) -> None:
+ """Modify a batch of documents, using pre-computed scores.
+
+ docs (Iterable[Doc]): The documents to modify.
+ kb_ids (List[str]): The IDs to set, produced by EntityLinker.predict.
+
+ DOCS: https://spacy.io/api/entitylinker#set_annotations
+ """
+ count_ents = len([ent for doc in docs for ent in doc.ents])
+ if count_ents != len(kb_ids):
+ raise ValueError(Errors.E148.format(ents=count_ents, ids=len(kb_ids)))
+ i = 0
+ overwrite = self.cfg["overwrite"]
+ for doc in docs:
+ for ent in doc.ents:
+ kb_id = kb_ids[i]
+ i += 1
+ for token in ent:
+ if token.ent_kb_id == 0 or overwrite:
+ token.ent_kb_id_ = kb_id
+
+ def to_bytes(self, *, exclude=tuple()):
+ """Serialize the pipe to a bytestring.
+
+ exclude (Iterable[str]): String names of serialization fields to exclude.
+ RETURNS (bytes): The serialized object.
+
+ DOCS: https://spacy.io/api/entitylinker#to_bytes
+ """
+ self._validate_serialization_attrs()
+ serialize = {}
+ if hasattr(self, "cfg") and self.cfg is not None:
+ serialize["cfg"] = lambda: srsly.json_dumps(self.cfg)
+ serialize["vocab"] = lambda: self.vocab.to_bytes(exclude=exclude)
+ serialize["kb"] = self.kb.to_bytes
+ serialize["model"] = self.model.to_bytes
+ return util.to_bytes(serialize, exclude)
+
+ def from_bytes(self, bytes_data, *, exclude=tuple()):
+ """Load the pipe from a bytestring.
+
+ exclude (Iterable[str]): String names of serialization fields to exclude.
+ RETURNS (TrainablePipe): The loaded object.
+
+ DOCS: https://spacy.io/api/entitylinker#from_bytes
+ """
+ self._validate_serialization_attrs()
+
+ def load_model(b):
+ try:
+ self.model.from_bytes(b)
+ except AttributeError:
+ raise ValueError(Errors.E149) from None
+
+ deserialize = {}
+ if hasattr(self, "cfg") and self.cfg is not None:
+ deserialize["cfg"] = lambda b: self.cfg.update(srsly.json_loads(b))
+ deserialize["vocab"] = lambda b: self.vocab.from_bytes(b, exclude=exclude)
+ deserialize["kb"] = lambda b: self.kb.from_bytes(b)
+ deserialize["model"] = load_model
+ util.from_bytes(bytes_data, deserialize, exclude)
+ return self
+
+ def to_disk(
+ self, path: Union[str, Path], *, exclude: Iterable[str] = SimpleFrozenList()
+ ) -> None:
+ """Serialize the pipe to disk.
+
+ path (str / Path): Path to a directory.
+ exclude (Iterable[str]): String names of serialization fields to exclude.
+
+ DOCS: https://spacy.io/api/entitylinker#to_disk
+ """
+ serialize = {}
+ serialize["vocab"] = lambda p: self.vocab.to_disk(p, exclude=exclude)
+ serialize["cfg"] = lambda p: srsly.write_json(p, self.cfg)
+ serialize["kb"] = lambda p: self.kb.to_disk(p)
+ serialize["model"] = lambda p: self.model.to_disk(p)
+ util.to_disk(path, serialize, exclude)
+
+ def from_disk(
+ self, path: Union[str, Path], *, exclude: Iterable[str] = SimpleFrozenList()
+ ) -> "EntityLinker_v1":
+ """Load the pipe from disk. Modifies the object in place and returns it.
+
+ path (str / Path): Path to a directory.
+ exclude (Iterable[str]): String names of serialization fields to exclude.
+ RETURNS (EntityLinker): The modified EntityLinker object.
+
+ DOCS: https://spacy.io/api/entitylinker#from_disk
+ """
+
+ def load_model(p):
+ try:
+ with p.open("rb") as infile:
+ self.model.from_bytes(infile.read())
+ except AttributeError:
+ raise ValueError(Errors.E149) from None
+
+ deserialize: Dict[str, Callable[[Any], Any]] = {}
+ deserialize["cfg"] = lambda p: self.cfg.update(deserialize_config(p))
+ deserialize["vocab"] = lambda p: self.vocab.from_disk(p, exclude=exclude)
+ deserialize["kb"] = lambda p: self.kb.from_disk(p)
+ deserialize["model"] = load_model
+ util.from_disk(path, deserialize, exclude)
+ return self
+
+ def rehearse(self, examples, *, sgd=None, losses=None, **config):
+ raise NotImplementedError
+
+ def add_label(self, label):
+ raise NotImplementedError
diff --git a/spacy/pipeline/morphologizer.pyx b/spacy/pipeline/morphologizer.pyx
index 73d3799b1..24f98508f 100644
--- a/spacy/pipeline/morphologizer.pyx
+++ b/spacy/pipeline/morphologizer.pyx
@@ -25,7 +25,7 @@ BACKWARD_EXTEND = False
default_model_config = """
[model]
-@architectures = "spacy.Tagger.v1"
+@architectures = "spacy.Tagger.v2"
[model.tok2vec]
@architectures = "spacy.Tok2Vec.v2"
diff --git a/spacy/pipeline/ner.pyx b/spacy/pipeline/ner.pyx
index 4835a8c4b..25f48c9f8 100644
--- a/spacy/pipeline/ner.pyx
+++ b/spacy/pipeline/ner.pyx
@@ -6,10 +6,10 @@ from thinc.api import Model, Config
from ._parser_internals.transition_system import TransitionSystem
from .transition_parser cimport Parser
from ._parser_internals.ner cimport BiluoPushDown
-
from ..language import Language
from ..scorer import get_ner_prf, PRFScore
from ..util import registry
+from ..training import remove_bilu_prefix
default_model_config = """
@@ -242,7 +242,7 @@ cdef class EntityRecognizer(Parser):
def labels(self):
# Get the labels from the model by looking at the available moves, e.g.
# B-PERSON, I-PERSON, L-PERSON, U-PERSON
- labels = set(move.split("-")[1] for move in self.move_names
+ labels = set(remove_bilu_prefix(move) for move in self.move_names
if move[0] in ("B", "I", "L", "U"))
return tuple(sorted(labels))
diff --git a/spacy/pipeline/pipe.pyx b/spacy/pipeline/pipe.pyx
index d24e4d574..8407acc45 100644
--- a/spacy/pipeline/pipe.pyx
+++ b/spacy/pipeline/pipe.pyx
@@ -1,4 +1,4 @@
-# cython: infer_types=True, profile=True
+# cython: infer_types=True, profile=True, binding=True
from typing import Optional, Tuple, Iterable, Iterator, Callable, Union, Dict
import srsly
import warnings
@@ -31,7 +31,7 @@ cdef class Pipe:
and returned. This usually happens under the hood when the nlp object
is called on a text and all components are applied to the Doc.
- docs (Doc): The Doc to process.
+ doc (Doc): The Doc to process.
RETURNS (Doc): The processed Doc.
DOCS: https://spacy.io/api/pipe#call
diff --git a/spacy/pipeline/senter.pyx b/spacy/pipeline/senter.pyx
index 6d00e829d..6808fe70e 100644
--- a/spacy/pipeline/senter.pyx
+++ b/spacy/pipeline/senter.pyx
@@ -20,7 +20,7 @@ BACKWARD_OVERWRITE = False
default_model_config = """
[model]
-@architectures = "spacy.Tagger.v1"
+@architectures = "spacy.Tagger.v2"
[model.tok2vec]
@architectures = "spacy.HashEmbedCNN.v2"
diff --git a/spacy/pipeline/span_ruler.py b/spacy/pipeline/span_ruler.py
new file mode 100644
index 000000000..b0669c0ef
--- /dev/null
+++ b/spacy/pipeline/span_ruler.py
@@ -0,0 +1,585 @@
+from typing import Optional, Union, List, Dict, Tuple, Iterable, Any, Callable
+from typing import Sequence, Set, cast
+import warnings
+from functools import partial
+from pathlib import Path
+import srsly
+
+from .pipe import Pipe
+from ..training import Example
+from ..language import Language
+from ..errors import Errors, Warnings
+from ..util import ensure_path, SimpleFrozenList, registry
+from ..tokens import Doc, Span
+from ..scorer import Scorer
+from ..matcher import Matcher, PhraseMatcher
+from ..matcher.levenshtein import levenshtein_compare
+from .. import util
+
+PatternType = Dict[str, Union[str, List[Dict[str, Any]]]]
+DEFAULT_SPANS_KEY = "ruler"
+
+
+@Language.factory(
+ "future_entity_ruler",
+ assigns=["doc.ents"],
+ default_config={
+ "phrase_matcher_attr": None,
+ "validate": False,
+ "overwrite_ents": False,
+ "scorer": {"@scorers": "spacy.entity_ruler_scorer.v1"},
+ "ent_id_sep": "__unused__",
+ "matcher_fuzzy_compare": {"@misc": "spacy.levenshtein_compare.v1"},
+ },
+ default_score_weights={
+ "ents_f": 1.0,
+ "ents_p": 0.0,
+ "ents_r": 0.0,
+ "ents_per_type": None,
+ },
+)
+def make_entity_ruler(
+ nlp: Language,
+ name: str,
+ phrase_matcher_attr: Optional[Union[int, str]],
+ matcher_fuzzy_compare: Callable,
+ validate: bool,
+ overwrite_ents: bool,
+ scorer: Optional[Callable],
+ ent_id_sep: str,
+):
+ if overwrite_ents:
+ ents_filter = prioritize_new_ents_filter
+ else:
+ ents_filter = prioritize_existing_ents_filter
+ return SpanRuler(
+ nlp,
+ name,
+ spans_key=None,
+ spans_filter=None,
+ annotate_ents=True,
+ ents_filter=ents_filter,
+ phrase_matcher_attr=phrase_matcher_attr,
+ matcher_fuzzy_compare=matcher_fuzzy_compare,
+ validate=validate,
+ overwrite=False,
+ scorer=scorer,
+ )
+
+
+@Language.factory(
+ "span_ruler",
+ assigns=["doc.spans"],
+ default_config={
+ "spans_key": DEFAULT_SPANS_KEY,
+ "spans_filter": None,
+ "annotate_ents": False,
+ "ents_filter": {"@misc": "spacy.first_longest_spans_filter.v1"},
+ "phrase_matcher_attr": None,
+ "matcher_fuzzy_compare": {"@misc": "spacy.levenshtein_compare.v1"},
+ "validate": False,
+ "overwrite": True,
+ "scorer": {
+ "@scorers": "spacy.overlapping_labeled_spans_scorer.v1",
+ "spans_key": DEFAULT_SPANS_KEY,
+ },
+ },
+ default_score_weights={
+ f"spans_{DEFAULT_SPANS_KEY}_f": 1.0,
+ f"spans_{DEFAULT_SPANS_KEY}_p": 0.0,
+ f"spans_{DEFAULT_SPANS_KEY}_r": 0.0,
+ f"spans_{DEFAULT_SPANS_KEY}_per_type": None,
+ },
+)
+def make_span_ruler(
+ nlp: Language,
+ name: str,
+ spans_key: Optional[str],
+ spans_filter: Optional[Callable[[Iterable[Span], Iterable[Span]], Iterable[Span]]],
+ annotate_ents: bool,
+ ents_filter: Callable[[Iterable[Span], Iterable[Span]], Iterable[Span]],
+ phrase_matcher_attr: Optional[Union[int, str]],
+ matcher_fuzzy_compare: Callable,
+ validate: bool,
+ overwrite: bool,
+ scorer: Optional[Callable],
+):
+ return SpanRuler(
+ nlp,
+ name,
+ spans_key=spans_key,
+ spans_filter=spans_filter,
+ annotate_ents=annotate_ents,
+ ents_filter=ents_filter,
+ phrase_matcher_attr=phrase_matcher_attr,
+ matcher_fuzzy_compare=matcher_fuzzy_compare,
+ validate=validate,
+ overwrite=overwrite,
+ scorer=scorer,
+ )
+
+
+def prioritize_new_ents_filter(
+ entities: Iterable[Span], spans: Iterable[Span]
+) -> List[Span]:
+ """Merge entities and spans into one list without overlaps by allowing
+ spans to overwrite any entities that they overlap with. Intended to
+ replicate the overwrite_ents=True behavior from the EntityRuler.
+
+ entities (Iterable[Span]): The entities, already filtered for overlaps.
+ spans (Iterable[Span]): The spans to merge, may contain overlaps.
+ RETURNS (List[Span]): Filtered list of non-overlapping spans.
+ """
+ get_sort_key = lambda span: (span.end - span.start, -span.start)
+ spans = sorted(spans, key=get_sort_key, reverse=True)
+ entities = list(entities)
+ new_entities = []
+ seen_tokens: Set[int] = set()
+ for span in spans:
+ start = span.start
+ end = span.end
+ if all(token.i not in seen_tokens for token in span):
+ new_entities.append(span)
+ entities = [e for e in entities if not (e.start < end and e.end > start)]
+ seen_tokens.update(range(start, end))
+ return entities + new_entities
+
+
+@registry.misc("spacy.prioritize_new_ents_filter.v1")
+def make_prioritize_new_ents_filter():
+ return prioritize_new_ents_filter
+
+
+def prioritize_existing_ents_filter(
+ entities: Iterable[Span], spans: Iterable[Span]
+) -> List[Span]:
+ """Merge entities and spans into one list without overlaps by prioritizing
+ existing entities. Intended to replicate the overwrite_ents=False behavior
+ from the EntityRuler.
+
+ entities (Iterable[Span]): The entities, already filtered for overlaps.
+ spans (Iterable[Span]): The spans to merge, may contain overlaps.
+ RETURNS (List[Span]): Filtered list of non-overlapping spans.
+ """
+ get_sort_key = lambda span: (span.end - span.start, -span.start)
+ spans = sorted(spans, key=get_sort_key, reverse=True)
+ entities = list(entities)
+ new_entities = []
+ seen_tokens: Set[int] = set()
+ seen_tokens.update(*(range(ent.start, ent.end) for ent in entities))
+ for span in spans:
+ start = span.start
+ end = span.end
+ if all(token.i not in seen_tokens for token in span):
+ new_entities.append(span)
+ seen_tokens.update(range(start, end))
+ return entities + new_entities
+
+
+@registry.misc("spacy.prioritize_existing_ents_filter.v1")
+def make_preserve_existing_ents_filter():
+ return prioritize_existing_ents_filter
+
+
+def overlapping_labeled_spans_score(
+ examples: Iterable[Example], *, spans_key=DEFAULT_SPANS_KEY, **kwargs
+) -> Dict[str, Any]:
+ kwargs = dict(kwargs)
+ attr_prefix = f"spans_"
+ kwargs.setdefault("attr", f"{attr_prefix}{spans_key}")
+ kwargs.setdefault("allow_overlap", True)
+ kwargs.setdefault("labeled", True)
+ kwargs.setdefault(
+ "getter", lambda doc, key: doc.spans.get(key[len(attr_prefix) :], [])
+ )
+ kwargs.setdefault("has_annotation", lambda doc: spans_key in doc.spans)
+ return Scorer.score_spans(examples, **kwargs)
+
+
+@registry.scorers("spacy.overlapping_labeled_spans_scorer.v1")
+def make_overlapping_labeled_spans_scorer(spans_key: str = DEFAULT_SPANS_KEY):
+ return partial(overlapping_labeled_spans_score, spans_key=spans_key)
+
+
+class SpanRuler(Pipe):
+ """The SpanRuler lets you add spans to the `Doc.spans` using token-based
+ rules or exact phrase matches.
+
+ DOCS: https://spacy.io/api/spanruler
+ USAGE: https://spacy.io/usage/rule-based-matching#spanruler
+ """
+
+ def __init__(
+ self,
+ nlp: Language,
+ name: str = "span_ruler",
+ *,
+ spans_key: Optional[str] = DEFAULT_SPANS_KEY,
+ spans_filter: Optional[
+ Callable[[Iterable[Span], Iterable[Span]], Iterable[Span]]
+ ] = None,
+ annotate_ents: bool = False,
+ ents_filter: Callable[
+ [Iterable[Span], Iterable[Span]], Iterable[Span]
+ ] = util.filter_chain_spans,
+ phrase_matcher_attr: Optional[Union[int, str]] = None,
+ matcher_fuzzy_compare: Callable = levenshtein_compare,
+ validate: bool = False,
+ overwrite: bool = False,
+ scorer: Optional[Callable] = partial(
+ overlapping_labeled_spans_score, spans_key=DEFAULT_SPANS_KEY
+ ),
+ ) -> None:
+ """Initialize the span ruler. If patterns are supplied here, they
+ need to be a list of dictionaries with a `"label"` and `"pattern"`
+ key. A pattern can either be a token pattern (list) or a phrase pattern
+ (string). For example: `{'label': 'ORG', 'pattern': 'Apple'}`.
+
+ nlp (Language): The shared nlp object to pass the vocab to the matchers
+ and process phrase patterns.
+ name (str): Instance name of the current pipeline component. Typically
+ passed in automatically from the factory when the component is
+ added. Used to disable the current span ruler while creating
+ phrase patterns with the nlp object.
+ spans_key (Optional[str]): The spans key to save the spans under. If
+ `None`, no spans are saved. Defaults to "ruler".
+ spans_filter (Optional[Callable[[Iterable[Span], Iterable[Span]], List[Span]]):
+ The optional method to filter spans before they are assigned to
+ doc.spans. Defaults to `None`.
+ annotate_ents (bool): Whether to save spans to doc.ents. Defaults to
+ `False`.
+ ents_filter (Callable[[Iterable[Span], Iterable[Span]], List[Span]]):
+ The method to filter spans before they are assigned to doc.ents.
+ Defaults to `util.filter_chain_spans`.
+ phrase_matcher_attr (Optional[Union[int, str]]): Token attribute to
+ match on, passed to the internal PhraseMatcher as `attr`. Defaults
+ to `None`.
+ matcher_fuzzy_compare (Callable): The fuzzy comparison method for the
+ internal Matcher. Defaults to
+ spacy.matcher.levenshtein.levenshtein_compare.
+ validate (bool): Whether patterns should be validated, passed to
+ Matcher and PhraseMatcher as `validate`.
+ overwrite (bool): Whether to remove any existing spans under this spans
+ key if `spans_key` is set, and/or to remove any ents under `doc.ents` if
+ `annotate_ents` is set. Defaults to `True`.
+ scorer (Optional[Callable]): The scoring method. Defaults to
+ spacy.pipeline.span_ruler.overlapping_labeled_spans_score.
+
+ DOCS: https://spacy.io/api/spanruler#init
+ """
+ self.nlp = nlp
+ self.name = name
+ self.spans_key = spans_key
+ self.annotate_ents = annotate_ents
+ self.phrase_matcher_attr = phrase_matcher_attr
+ self.validate = validate
+ self.overwrite = overwrite
+ self.spans_filter = spans_filter
+ self.ents_filter = ents_filter
+ self.scorer = scorer
+ self.matcher_fuzzy_compare = matcher_fuzzy_compare
+ self._match_label_id_map: Dict[int, Dict[str, str]] = {}
+ self.clear()
+
+ def __len__(self) -> int:
+ """The number of all labels added to the span ruler."""
+ return len(self._patterns)
+
+ def __contains__(self, label: str) -> bool:
+ """Whether a label is present in the patterns."""
+ for label_id in self._match_label_id_map.values():
+ if label_id["label"] == label:
+ return True
+ return False
+
+ @property
+ def key(self) -> Optional[str]:
+ """Key of the doc.spans dict to save the spans under."""
+ return self.spans_key
+
+ def __call__(self, doc: Doc) -> Doc:
+ """Find matches in document and add them as entities.
+
+ doc (Doc): The Doc object in the pipeline.
+ RETURNS (Doc): The Doc with added entities, if available.
+
+ DOCS: https://spacy.io/api/spanruler#call
+ """
+ error_handler = self.get_error_handler()
+ try:
+ matches = self.match(doc)
+ self.set_annotations(doc, matches)
+ return doc
+ except Exception as e:
+ return error_handler(self.name, self, [doc], e)
+
+ def match(self, doc: Doc):
+ self._require_patterns()
+ with warnings.catch_warnings():
+ warnings.filterwarnings("ignore", message="\\[W036")
+ matches = cast(
+ List[Tuple[int, int, int]],
+ list(self.matcher(doc)) + list(self.phrase_matcher(doc)),
+ )
+ deduplicated_matches = set(
+ Span(
+ doc,
+ start,
+ end,
+ label=self._match_label_id_map[m_id]["label"],
+ span_id=self._match_label_id_map[m_id]["id"],
+ )
+ for m_id, start, end in matches
+ if start != end
+ )
+ return sorted(list(deduplicated_matches))
+
+ def set_annotations(self, doc, matches):
+ """Modify the document in place"""
+ # set doc.spans if spans_key is set
+ if self.key:
+ spans = []
+ if self.key in doc.spans and not self.overwrite:
+ spans = doc.spans[self.key]
+ spans.extend(
+ self.spans_filter(spans, matches) if self.spans_filter else matches
+ )
+ doc.spans[self.key] = spans
+ # set doc.ents if annotate_ents is set
+ if self.annotate_ents:
+ spans = []
+ if not self.overwrite:
+ spans = list(doc.ents)
+ spans = self.ents_filter(spans, matches)
+ try:
+ doc.ents = sorted(spans)
+ except ValueError:
+ raise ValueError(Errors.E854)
+
+ @property
+ def labels(self) -> Tuple[str, ...]:
+ """All labels present in the match patterns.
+
+ RETURNS (set): The string labels.
+
+ DOCS: https://spacy.io/api/spanruler#labels
+ """
+ return tuple(sorted(set([cast(str, p["label"]) for p in self._patterns])))
+
+ @property
+ def ids(self) -> Tuple[str, ...]:
+ """All IDs present in the match patterns.
+
+ RETURNS (set): The string IDs.
+
+ DOCS: https://spacy.io/api/spanruler#ids
+ """
+ return tuple(
+ sorted(set([cast(str, p.get("id")) for p in self._patterns]) - set([None]))
+ )
+
+ def initialize(
+ self,
+ get_examples: Callable[[], Iterable[Example]],
+ *,
+ nlp: Optional[Language] = None,
+ patterns: Optional[Sequence[PatternType]] = None,
+ ):
+ """Initialize the pipe for training.
+
+ get_examples (Callable[[], Iterable[Example]]): Function that
+ returns a representative sample of gold-standard Example objects.
+ nlp (Language): The current nlp object the component is part of.
+ patterns (Optional[Iterable[PatternType]]): The list of patterns.
+
+ DOCS: https://spacy.io/api/spanruler#initialize
+ """
+ self.clear()
+ if patterns:
+ self.add_patterns(patterns) # type: ignore[arg-type]
+
+ @property
+ def patterns(self) -> List[PatternType]:
+ """Get all patterns that were added to the span ruler.
+
+ RETURNS (list): The original patterns, one dictionary per pattern.
+
+ DOCS: https://spacy.io/api/spanruler#patterns
+ """
+ return self._patterns
+
+ def add_patterns(self, patterns: List[PatternType]) -> None:
+ """Add patterns to the span ruler. A pattern can either be a token
+ pattern (list of dicts) or a phrase pattern (string). For example:
+ {'label': 'ORG', 'pattern': 'Apple'}
+ {'label': 'ORG', 'pattern': 'Apple', 'id': 'apple'}
+ {'label': 'GPE', 'pattern': [{'lower': 'san'}, {'lower': 'francisco'}]}
+
+ patterns (list): The patterns to add.
+
+ DOCS: https://spacy.io/api/spanruler#add_patterns
+ """
+
+ # disable the nlp components after this one in case they haven't been
+ # initialized / deserialized yet
+ try:
+ current_index = -1
+ for i, (name, pipe) in enumerate(self.nlp.pipeline):
+ if self == pipe:
+ current_index = i
+ break
+ subsequent_pipes = [pipe for pipe in self.nlp.pipe_names[current_index:]]
+ except ValueError:
+ subsequent_pipes = []
+ with self.nlp.select_pipes(disable=subsequent_pipes):
+ phrase_pattern_labels = []
+ phrase_pattern_texts = []
+ for entry in patterns:
+ p_label = cast(str, entry["label"])
+ p_id = cast(str, entry.get("id", ""))
+ label = repr((p_label, p_id))
+ self._match_label_id_map[self.nlp.vocab.strings.as_int(label)] = {
+ "label": p_label,
+ "id": p_id,
+ }
+ if isinstance(entry["pattern"], str):
+ phrase_pattern_labels.append(label)
+ phrase_pattern_texts.append(entry["pattern"])
+ elif isinstance(entry["pattern"], list):
+ self.matcher.add(label, [entry["pattern"]])
+ else:
+ raise ValueError(Errors.E097.format(pattern=entry["pattern"]))
+ self._patterns.append(entry)
+ for label, pattern in zip(
+ phrase_pattern_labels,
+ self.nlp.pipe(phrase_pattern_texts),
+ ):
+ self.phrase_matcher.add(label, [pattern])
+
+ def clear(self) -> None:
+ """Reset all patterns.
+
+ RETURNS: None
+ DOCS: https://spacy.io/api/spanruler#clear
+ """
+ self._patterns: List[PatternType] = []
+ self.matcher: Matcher = Matcher(
+ self.nlp.vocab,
+ validate=self.validate,
+ fuzzy_compare=self.matcher_fuzzy_compare,
+ )
+ self.phrase_matcher: PhraseMatcher = PhraseMatcher(
+ self.nlp.vocab,
+ attr=self.phrase_matcher_attr,
+ validate=self.validate,
+ )
+
+ def remove(self, label: str) -> None:
+ """Remove a pattern by its label.
+
+ label (str): Label of the pattern to be removed.
+ RETURNS: None
+ DOCS: https://spacy.io/api/spanruler#remove
+ """
+ if label not in self:
+ raise ValueError(
+ Errors.E1024.format(attr_type="label", label=label, component=self.name)
+ )
+ self._patterns = [p for p in self._patterns if p["label"] != label]
+ for m_label in self._match_label_id_map:
+ if self._match_label_id_map[m_label]["label"] == label:
+ m_label_str = self.nlp.vocab.strings.as_string(m_label)
+ if m_label_str in self.phrase_matcher:
+ self.phrase_matcher.remove(m_label_str)
+ if m_label_str in self.matcher:
+ self.matcher.remove(m_label_str)
+
+ def remove_by_id(self, pattern_id: str) -> None:
+ """Remove a pattern by its pattern ID.
+
+ pattern_id (str): ID of the pattern to be removed.
+ RETURNS: None
+ DOCS: https://spacy.io/api/spanruler#remove_by_id
+ """
+ orig_len = len(self)
+ self._patterns = [p for p in self._patterns if p.get("id") != pattern_id]
+ if orig_len == len(self):
+ raise ValueError(
+ Errors.E1024.format(
+ attr_type="ID", label=pattern_id, component=self.name
+ )
+ )
+ for m_label in self._match_label_id_map:
+ if self._match_label_id_map[m_label]["id"] == pattern_id:
+ m_label_str = self.nlp.vocab.strings.as_string(m_label)
+ if m_label_str in self.phrase_matcher:
+ self.phrase_matcher.remove(m_label_str)
+ if m_label_str in self.matcher:
+ self.matcher.remove(m_label_str)
+
+ def _require_patterns(self) -> None:
+ """Raise a warning if this component has no patterns defined."""
+ if len(self) == 0:
+ warnings.warn(Warnings.W036.format(name=self.name))
+
+ def from_bytes(
+ self, bytes_data: bytes, *, exclude: Iterable[str] = SimpleFrozenList()
+ ) -> "SpanRuler":
+ """Load the span ruler from a bytestring.
+
+ bytes_data (bytes): The bytestring to load.
+ RETURNS (SpanRuler): The loaded span ruler.
+
+ DOCS: https://spacy.io/api/spanruler#from_bytes
+ """
+ self.clear()
+ deserializers = {
+ "patterns": lambda b: self.add_patterns(srsly.json_loads(b)),
+ }
+ util.from_bytes(bytes_data, deserializers, exclude)
+ return self
+
+ def to_bytes(self, *, exclude: Iterable[str] = SimpleFrozenList()) -> bytes:
+ """Serialize the span ruler to a bytestring.
+
+ RETURNS (bytes): The serialized patterns.
+
+ DOCS: https://spacy.io/api/spanruler#to_bytes
+ """
+ serializers = {
+ "patterns": lambda: srsly.json_dumps(self.patterns),
+ }
+ return util.to_bytes(serializers, exclude)
+
+ def from_disk(
+ self, path: Union[str, Path], *, exclude: Iterable[str] = SimpleFrozenList()
+ ) -> "SpanRuler":
+ """Load the span ruler from a directory.
+
+ path (Union[str, Path]): A path to a directory.
+ RETURNS (SpanRuler): The loaded span ruler.
+
+ DOCS: https://spacy.io/api/spanruler#from_disk
+ """
+ self.clear()
+ path = ensure_path(path)
+ deserializers = {
+ "patterns": lambda p: self.add_patterns(srsly.read_jsonl(p)),
+ }
+ util.from_disk(path, deserializers, {})
+ return self
+
+ def to_disk(
+ self, path: Union[str, Path], *, exclude: Iterable[str] = SimpleFrozenList()
+ ) -> None:
+ """Save the span ruler patterns to a directory.
+
+ path (Union[str, Path]): A path to a directory.
+
+ DOCS: https://spacy.io/api/spanruler#to_disk
+ """
+ path = ensure_path(path)
+ serializers = {
+ "patterns": lambda p: srsly.write_jsonl(p, self.patterns),
+ }
+ util.to_disk(path, serializers, {})
diff --git a/spacy/pipeline/spancat.py b/spacy/pipeline/spancat.py
index 3759466d1..a3388e81a 100644
--- a/spacy/pipeline/spancat.py
+++ b/spacy/pipeline/spancat.py
@@ -1,7 +1,7 @@
-from typing import List, Dict, Callable, Tuple, Optional, Iterable, Any, cast
+from typing import List, Dict, Callable, Tuple, Optional, Iterable, Any
from thinc.api import Config, Model, get_current_ops, set_dropout_rate, Ops
from thinc.api import Optimizer
-from thinc.types import Ragged, Ints2d, Floats2d, Ints1d
+from thinc.types import Ragged, Ints2d, Floats2d
import numpy
@@ -26,17 +26,17 @@ scorer = {"@layers": "spacy.LinearLogistic.v1"}
hidden_size = 128
[model.tok2vec]
-@architectures = "spacy.Tok2Vec.v1"
+@architectures = "spacy.Tok2Vec.v2"
[model.tok2vec.embed]
-@architectures = "spacy.MultiHashEmbed.v1"
+@architectures = "spacy.MultiHashEmbed.v2"
width = 96
rows = [5000, 2000, 1000, 1000]
attrs = ["ORTH", "PREFIX", "SUFFIX", "SHAPE"]
include_static_vectors = false
[model.tok2vec.encode]
-@architectures = "spacy.MaxoutWindowEncoder.v1"
+@architectures = "spacy.MaxoutWindowEncoder.v2"
width = ${model.tok2vec.embed.width}
window_size = 1
maxout_pieces = 3
@@ -75,7 +75,7 @@ def build_ngram_suggester(sizes: List[int]) -> Suggester:
if spans:
assert spans[-1].ndim == 2, spans[-1].shape
lengths.append(length)
- lengths_array = cast(Ints1d, ops.asarray(lengths, dtype="i"))
+ lengths_array = ops.asarray1i(lengths)
if len(spans) > 0:
output = Ragged(ops.xp.vstack(spans), lengths_array)
else:
@@ -133,6 +133,9 @@ def make_spancat(
spans_key (str): Key of the doc.spans dict to save the spans under. During
initialization and training, the component will look for spans on the
reference document under the same key.
+ scorer (Optional[Callable]): The scoring method. Defaults to
+ Scorer.score_spans for the Doc.spans[spans_key] with overlapping
+ spans allowed.
threshold (float): Minimum probability to consider a prediction positive.
Spans with a positive prediction will be saved on the Doc. Defaults to
0.5.
@@ -269,9 +272,30 @@ class SpanCategorizer(TrainablePipe):
DOCS: https://spacy.io/api/spancategorizer#predict
"""
indices = self.suggester(docs, ops=self.model.ops)
- scores = self.model.predict((docs, indices)) # type: ignore
+ if indices.lengths.sum() == 0:
+ scores = self.model.ops.alloc2f(0, 0)
+ else:
+ scores = self.model.predict((docs, indices)) # type: ignore
return indices, scores
+ def set_candidates(
+ self, docs: Iterable[Doc], *, candidates_key: str = "candidates"
+ ) -> None:
+ """Use the spancat suggester to add a list of span candidates to a list of docs.
+ This method is intended to be used for debugging purposes.
+
+ docs (Iterable[Doc]): The documents to modify.
+ candidates_key (str): Key of the Doc.spans dict to save the candidate spans under.
+
+ DOCS: https://spacy.io/api/spancategorizer#set_candidates
+ """
+ suggester_output = self.suggester(docs, ops=self.model.ops)
+
+ for candidates, doc in zip(suggester_output, docs): # type: ignore
+ doc.spans[candidates_key] = []
+ for index in candidates.dataXd:
+ doc.spans[candidates_key].append(doc[index[0] : index[1]])
+
def set_annotations(self, docs: Iterable[Doc], indices_scores) -> None:
"""Modify a batch of Doc objects, using pre-computed scores.
diff --git a/spacy/pipeline/tagger.pyx b/spacy/pipeline/tagger.pyx
index e21a9096e..d6ecbf084 100644
--- a/spacy/pipeline/tagger.pyx
+++ b/spacy/pipeline/tagger.pyx
@@ -27,7 +27,7 @@ BACKWARD_OVERWRITE = False
default_model_config = """
[model]
-@architectures = "spacy.Tagger.v1"
+@architectures = "spacy.Tagger.v2"
[model.tok2vec]
@architectures = "spacy.HashEmbedCNN.v2"
diff --git a/spacy/pipeline/textcat.py b/spacy/pipeline/textcat.py
index bc3f127fc..650a01949 100644
--- a/spacy/pipeline/textcat.py
+++ b/spacy/pipeline/textcat.py
@@ -24,8 +24,8 @@ single_label_default_config = """
[model.tok2vec.embed]
@architectures = "spacy.MultiHashEmbed.v2"
width = 64
-rows = [2000, 2000, 1000, 1000, 1000, 1000]
-attrs = ["ORTH", "LOWER", "PREFIX", "SUFFIX", "SHAPE", "ID"]
+rows = [2000, 2000, 500, 1000, 500]
+attrs = ["NORM", "LOWER", "PREFIX", "SUFFIX", "SHAPE"]
include_static_vectors = false
[model.tok2vec.encode]
@@ -72,9 +72,9 @@ subword_features = true
"textcat",
assigns=["doc.cats"],
default_config={
- "threshold": 0.5,
+ "threshold": 0.0,
"model": DEFAULT_SINGLE_TEXTCAT_MODEL,
- "scorer": {"@scorers": "spacy.textcat_scorer.v1"},
+ "scorer": {"@scorers": "spacy.textcat_scorer.v2"},
},
default_score_weights={
"cats_score": 1.0,
@@ -87,7 +87,6 @@ subword_features = true
"cats_macro_f": None,
"cats_macro_auc": None,
"cats_f_per_type": None,
- "cats_macro_auc_per_type": None,
},
)
def make_textcat(
@@ -118,7 +117,7 @@ def textcat_score(examples: Iterable[Example], **kwargs) -> Dict[str, Any]:
)
-@registry.scorers("spacy.textcat_scorer.v1")
+@registry.scorers("spacy.textcat_scorer.v2")
def make_textcat_scorer():
return textcat_score
@@ -144,7 +143,8 @@ class TextCategorizer(TrainablePipe):
model (thinc.api.Model): The Thinc Model powering the pipeline component.
name (str): The component instance name, used to add entries to the
losses during training.
- threshold (float): Cutoff to consider a prediction "positive".
+ threshold (float): Unused, not needed for single-label (exclusive
+ classes) classification.
scorer (Optional[Callable]): The scoring method. Defaults to
Scorer.score_cats for the attribute "cats".
@@ -154,7 +154,11 @@ class TextCategorizer(TrainablePipe):
self.model = model
self.name = name
self._rehearsal_model = None
- cfg = {"labels": [], "threshold": threshold, "positive_label": None}
+ cfg: Dict[str, Any] = {
+ "labels": [],
+ "threshold": threshold,
+ "positive_label": None,
+ }
self.cfg = dict(cfg)
self.scorer = scorer
@@ -192,7 +196,7 @@ class TextCategorizer(TrainablePipe):
if not any(len(doc) for doc in docs):
# Handle cases where there are no tokens in any docs.
tensors = [doc.tensor for doc in docs]
- xp = get_array_module(tensors)
+ xp = self.model.ops.xp
scores = xp.zeros((len(list(docs)), len(self.labels)))
return scores
scores = self.model.predict(docs)
@@ -396,5 +400,9 @@ class TextCategorizer(TrainablePipe):
def _validate_categories(self, examples: Iterable[Example]):
"""Check whether the provided examples all have single-label cats annotations."""
for ex in examples:
- if list(ex.reference.cats.values()).count(1.0) > 1:
+ vals = list(ex.reference.cats.values())
+ if vals.count(1.0) > 1:
raise ValueError(Errors.E895.format(value=ex.reference.cats))
+ for val in vals:
+ if not (val == 1.0 or val == 0.0):
+ raise ValueError(Errors.E851.format(val=val))
diff --git a/spacy/pipeline/textcat_multilabel.py b/spacy/pipeline/textcat_multilabel.py
index e33a885f8..41c0e2f63 100644
--- a/spacy/pipeline/textcat_multilabel.py
+++ b/spacy/pipeline/textcat_multilabel.py
@@ -19,17 +19,17 @@ multi_label_default_config = """
@architectures = "spacy.TextCatEnsemble.v2"
[model.tok2vec]
-@architectures = "spacy.Tok2Vec.v1"
+@architectures = "spacy.Tok2Vec.v2"
[model.tok2vec.embed]
@architectures = "spacy.MultiHashEmbed.v2"
width = 64
-rows = [2000, 2000, 1000, 1000, 1000, 1000]
-attrs = ["ORTH", "LOWER", "PREFIX", "SUFFIX", "SHAPE", "ID"]
+rows = [2000, 2000, 500, 1000, 500]
+attrs = ["NORM", "LOWER", "PREFIX", "SUFFIX", "SHAPE"]
include_static_vectors = false
[model.tok2vec.encode]
-@architectures = "spacy.MaxoutWindowEncoder.v1"
+@architectures = "spacy.MaxoutWindowEncoder.v2"
width = ${model.tok2vec.embed.width}
window_size = 1
maxout_pieces = 3
@@ -74,7 +74,7 @@ subword_features = true
default_config={
"threshold": 0.5,
"model": DEFAULT_MULTI_TEXTCAT_MODEL,
- "scorer": {"@scorers": "spacy.textcat_multilabel_scorer.v1"},
+ "scorer": {"@scorers": "spacy.textcat_multilabel_scorer.v2"},
},
default_score_weights={
"cats_score": 1.0,
@@ -87,7 +87,6 @@ subword_features = true
"cats_macro_f": None,
"cats_macro_auc": None,
"cats_f_per_type": None,
- "cats_macro_auc_per_type": None,
},
)
def make_multilabel_textcat(
@@ -96,8 +95,8 @@ def make_multilabel_textcat(
model: Model[List[Doc], List[Floats2d]],
threshold: float,
scorer: Optional[Callable],
-) -> "TextCategorizer":
- """Create a TextCategorizer component. The text categorizer predicts categories
+) -> "MultiLabel_TextCategorizer":
+ """Create a MultiLabel_TextCategorizer component. The text categorizer predicts categories
over a whole document. It can learn one or more labels, and the labels are considered
to be non-mutually exclusive, which means that there can be zero or more labels
per doc).
@@ -105,6 +104,7 @@ def make_multilabel_textcat(
model (Model[List[Doc], List[Floats2d]]): A model instance that predicts
scores for each category.
threshold (float): Cutoff to consider a prediction "positive".
+ scorer (Optional[Callable]): The scoring method.
"""
return MultiLabel_TextCategorizer(
nlp.vocab, model, name, threshold=threshold, scorer=scorer
@@ -120,7 +120,7 @@ def textcat_multilabel_score(examples: Iterable[Example], **kwargs) -> Dict[str,
)
-@registry.scorers("spacy.textcat_multilabel_scorer.v1")
+@registry.scorers("spacy.textcat_multilabel_scorer.v2")
def make_textcat_multilabel_scorer():
return textcat_multilabel_score
@@ -147,6 +147,7 @@ class MultiLabel_TextCategorizer(TextCategorizer):
name (str): The component instance name, used to add entries to the
losses during training.
threshold (float): Cutoff to consider a prediction "positive".
+ scorer (Optional[Callable]): The scoring method.
DOCS: https://spacy.io/api/textcategorizer#init
"""
@@ -190,6 +191,8 @@ class MultiLabel_TextCategorizer(TextCategorizer):
for label in labels:
self.add_label(label)
subbatch = list(islice(get_examples(), 10))
+ self._validate_categories(subbatch)
+
doc_sample = [eg.reference for eg in subbatch]
label_sample, _ = self._examples_to_truth(subbatch)
self._require_labels()
@@ -200,4 +203,8 @@ class MultiLabel_TextCategorizer(TextCategorizer):
def _validate_categories(self, examples: Iterable[Example]):
"""This component allows any type of single- or multi-label annotations.
This method overwrites the more strict one from 'textcat'."""
- pass
+ # check that annotation values are valid
+ for ex in examples:
+ for val in ex.reference.cats.values():
+ if not (val == 1.0 or val == 0.0):
+ raise ValueError(Errors.E851.format(val=val))
diff --git a/spacy/pipeline/tok2vec.py b/spacy/pipeline/tok2vec.py
index 2e3dde3cb..c742aaeaa 100644
--- a/spacy/pipeline/tok2vec.py
+++ b/spacy/pipeline/tok2vec.py
@@ -123,9 +123,6 @@ class Tok2Vec(TrainablePipe):
width = self.model.get_dim("nO")
return [self.model.ops.alloc((0, width)) for doc in docs]
tokvecs = self.model.predict(docs)
- batch_id = Tok2VecListener.get_batch_id(docs)
- for listener in self.listeners:
- listener.receive(batch_id, tokvecs, _empty_backprop)
return tokvecs
def set_annotations(self, docs: Sequence[Doc], tokvecses) -> None:
@@ -286,8 +283,19 @@ class Tok2VecListener(Model):
def forward(model: Tok2VecListener, inputs, is_train: bool):
"""Supply the outputs from the upstream Tok2Vec component."""
if is_train:
- model.verify_inputs(inputs)
- return model._outputs, model._backprop
+ # This might occur during training when the tok2vec layer is frozen / hasn't been updated.
+ # In that case, it should be set to "annotating" so we can retrieve the embeddings from the doc.
+ if model._batch_id is None:
+ outputs = []
+ for doc in inputs:
+ if doc.tensor.size == 0:
+ raise ValueError(Errors.E203.format(name="tok2vec"))
+ else:
+ outputs.append(doc.tensor)
+ return outputs, _empty_backprop
+ else:
+ model.verify_inputs(inputs)
+ return model._outputs, model._backprop
else:
# This is pretty grim, but it's hard to do better :(.
# It's hard to avoid relying on the doc.tensor attribute, because the
@@ -306,7 +314,7 @@ def forward(model: Tok2VecListener, inputs, is_train: bool):
outputs.append(model.ops.alloc2f(len(doc), width))
else:
outputs.append(doc.tensor)
- return outputs, lambda dX: []
+ return outputs, _empty_backprop
def _empty_backprop(dX): # for pickling
diff --git a/spacy/pipeline/trainable_pipe.pyx b/spacy/pipeline/trainable_pipe.pyx
index 76b0733cf..3f0507d4b 100644
--- a/spacy/pipeline/trainable_pipe.pyx
+++ b/spacy/pipeline/trainable_pipe.pyx
@@ -1,4 +1,4 @@
-# cython: infer_types=True, profile=True
+# cython: infer_types=True, profile=True, binding=True
from typing import Iterable, Iterator, Optional, Dict, Tuple, Callable
import srsly
from thinc.api import set_dropout_rate, Model, Optimizer
diff --git a/spacy/pipeline/transition_parser.pxd b/spacy/pipeline/transition_parser.pxd
index bd5bad334..1521fde60 100644
--- a/spacy/pipeline/transition_parser.pxd
+++ b/spacy/pipeline/transition_parser.pxd
@@ -1,4 +1,5 @@
from cymem.cymem cimport Pool
+from thinc.backends.cblas cimport CBlas
from ..vocab cimport Vocab
from .trainable_pipe cimport TrainablePipe
@@ -12,7 +13,7 @@ cdef class Parser(TrainablePipe):
cdef readonly TransitionSystem moves
cdef public object _multitasks
- cdef void _parseC(self, StateC** states,
+ cdef void _parseC(self, CBlas cblas, StateC** states,
WeightsC weights, SizesC sizes) nogil
cdef void c_transition_batch(self, StateC** states, const float* scores,
diff --git a/spacy/pipeline/transition_parser.pyx b/spacy/pipeline/transition_parser.pyx
index 2571af102..1327db2ce 100644
--- a/spacy/pipeline/transition_parser.pyx
+++ b/spacy/pipeline/transition_parser.pyx
@@ -9,7 +9,7 @@ from libc.stdlib cimport calloc, free
import random
import srsly
-from thinc.api import set_dropout_rate, CupyOps
+from thinc.api import get_ops, set_dropout_rate, CupyOps, NumpyOps
from thinc.extra.search cimport Beam
import numpy.random
import numpy
@@ -30,6 +30,9 @@ from ..errors import Errors, Warnings
from .. import util
+NUMPY_OPS = NumpyOps()
+
+
cdef class Parser(TrainablePipe):
"""
Base class of the DependencyParser and EntityRecognizer.
@@ -259,6 +262,12 @@ cdef class Parser(TrainablePipe):
def greedy_parse(self, docs, drop=0.):
cdef vector[StateC*] states
cdef StateClass state
+ ops = self.model.ops
+ cdef CBlas cblas
+ if isinstance(ops, CupyOps):
+ cblas = NUMPY_OPS.cblas()
+ else:
+ cblas = ops.cblas()
self._ensure_labels_are_added(docs)
set_dropout_rate(self.model, drop)
batch = self.moves.init_batch(docs)
@@ -269,8 +278,7 @@ cdef class Parser(TrainablePipe):
states.push_back(state.c)
sizes = get_c_sizes(model, states.size())
with nogil:
- self._parseC(&states[0],
- weights, sizes)
+ self._parseC(cblas, &states[0], weights, sizes)
model.clear_memory()
del model
return batch
@@ -297,14 +305,13 @@ cdef class Parser(TrainablePipe):
del model
return list(batch)
- cdef void _parseC(self, StateC** states,
+ cdef void _parseC(self, CBlas cblas, StateC** states,
WeightsC weights, SizesC sizes) nogil:
cdef int i, j
cdef vector[StateC*] unfinished
cdef ActivationsC activations = alloc_activations(sizes)
while sizes.states >= 1:
- predict_states(&activations,
- states, &weights, sizes)
+ predict_states(cblas, &activations, states, &weights, sizes)
# Validate actions, argmax, take action.
self.c_transition_batch(states,
activations.scores, sizes.classes, sizes.states)
diff --git a/spacy/schemas.py b/spacy/schemas.py
index 1dfd8ee85..140592dcd 100644
--- a/spacy/schemas.py
+++ b/spacy/schemas.py
@@ -3,12 +3,13 @@ from typing import Iterable, TypeVar, TYPE_CHECKING
from .compat import Literal
from enum import Enum
from pydantic import BaseModel, Field, ValidationError, validator, create_model
-from pydantic import StrictStr, StrictInt, StrictFloat, StrictBool
+from pydantic import StrictStr, StrictInt, StrictFloat, StrictBool, ConstrainedStr
from pydantic.main import ModelMetaclass
from thinc.api import Optimizer, ConfigValidationError, Model
from thinc.config import Promise
from collections import defaultdict
import inspect
+import re
from .attrs import NAMES
from .lookups import Lookups
@@ -104,7 +105,7 @@ def get_arg_model(
sig_args[param.name] = (annotation, default)
is_strict = strict and not has_variable
sig_args["__config__"] = ArgSchemaConfig if is_strict else ArgSchemaConfigExtra # type: ignore[assignment]
- return create_model(name, **sig_args) # type: ignore[arg-type, return-value]
+ return create_model(name, **sig_args) # type: ignore[call-overload, arg-type, return-value]
def validate_init_settings(
@@ -155,12 +156,40 @@ def validate_token_pattern(obj: list) -> List[str]:
class TokenPatternString(BaseModel):
- REGEX: Optional[StrictStr] = Field(None, alias="regex")
+ REGEX: Optional[Union[StrictStr, "TokenPatternString"]] = Field(None, alias="regex")
IN: Optional[List[StrictStr]] = Field(None, alias="in")
NOT_IN: Optional[List[StrictStr]] = Field(None, alias="not_in")
IS_SUBSET: Optional[List[StrictStr]] = Field(None, alias="is_subset")
IS_SUPERSET: Optional[List[StrictStr]] = Field(None, alias="is_superset")
INTERSECTS: Optional[List[StrictStr]] = Field(None, alias="intersects")
+ FUZZY: Optional[Union[StrictStr, "TokenPatternString"]] = Field(None, alias="fuzzy")
+ FUZZY1: Optional[Union[StrictStr, "TokenPatternString"]] = Field(
+ None, alias="fuzzy1"
+ )
+ FUZZY2: Optional[Union[StrictStr, "TokenPatternString"]] = Field(
+ None, alias="fuzzy2"
+ )
+ FUZZY3: Optional[Union[StrictStr, "TokenPatternString"]] = Field(
+ None, alias="fuzzy3"
+ )
+ FUZZY4: Optional[Union[StrictStr, "TokenPatternString"]] = Field(
+ None, alias="fuzzy4"
+ )
+ FUZZY5: Optional[Union[StrictStr, "TokenPatternString"]] = Field(
+ None, alias="fuzzy5"
+ )
+ FUZZY6: Optional[Union[StrictStr, "TokenPatternString"]] = Field(
+ None, alias="fuzzy6"
+ )
+ FUZZY7: Optional[Union[StrictStr, "TokenPatternString"]] = Field(
+ None, alias="fuzzy7"
+ )
+ FUZZY8: Optional[Union[StrictStr, "TokenPatternString"]] = Field(
+ None, alias="fuzzy8"
+ )
+ FUZZY9: Optional[Union[StrictStr, "TokenPatternString"]] = Field(
+ None, alias="fuzzy9"
+ )
class Config:
extra = "forbid"
@@ -180,12 +209,12 @@ class TokenPatternNumber(BaseModel):
IS_SUBSET: Optional[List[StrictInt]] = Field(None, alias="is_subset")
IS_SUPERSET: Optional[List[StrictInt]] = Field(None, alias="is_superset")
INTERSECTS: Optional[List[StrictInt]] = Field(None, alias="intersects")
- EQ: Union[StrictInt, StrictFloat] = Field(None, alias="==")
- NEQ: Union[StrictInt, StrictFloat] = Field(None, alias="!=")
- GEQ: Union[StrictInt, StrictFloat] = Field(None, alias=">=")
- LEQ: Union[StrictInt, StrictFloat] = Field(None, alias="<=")
- GT: Union[StrictInt, StrictFloat] = Field(None, alias=">")
- LT: Union[StrictInt, StrictFloat] = Field(None, alias="<")
+ EQ: Optional[Union[StrictInt, StrictFloat]] = Field(None, alias="==")
+ NEQ: Optional[Union[StrictInt, StrictFloat]] = Field(None, alias="!=")
+ GEQ: Optional[Union[StrictInt, StrictFloat]] = Field(None, alias=">=")
+ LEQ: Optional[Union[StrictInt, StrictFloat]] = Field(None, alias="<=")
+ GT: Optional[Union[StrictInt, StrictFloat]] = Field(None, alias=">")
+ LT: Optional[Union[StrictInt, StrictFloat]] = Field(None, alias="<")
class Config:
extra = "forbid"
@@ -198,13 +227,18 @@ class TokenPatternNumber(BaseModel):
return v
-class TokenPatternOperator(str, Enum):
+class TokenPatternOperatorSimple(str, Enum):
plus: StrictStr = StrictStr("+")
- start: StrictStr = StrictStr("*")
+ star: StrictStr = StrictStr("*")
question: StrictStr = StrictStr("?")
exclamation: StrictStr = StrictStr("!")
+class TokenPatternOperatorMinMax(ConstrainedStr):
+ regex = re.compile(r"^({\d+}|{\d+,\d*}|{\d*,\d+})$")
+
+
+TokenPatternOperator = Union[TokenPatternOperatorSimple, TokenPatternOperatorMinMax]
StringValue = Union[TokenPatternString, StrictStr]
NumberValue = Union[TokenPatternNumber, StrictInt, StrictFloat]
UnderscoreValue = Union[
@@ -323,6 +357,7 @@ class ConfigSchemaTraining(BaseModel):
frozen_components: List[str] = Field(..., title="Pipeline components that shouldn't be updated during training")
annotating_components: List[str] = Field(..., title="Pipeline components that should set annotations during training")
before_to_disk: Optional[Callable[["Language"], "Language"]] = Field(..., title="Optional callback to modify nlp object after training, before it's saved to disk")
+ before_update: Optional[Callable[["Language", Dict[str, Any]], None]] = Field(..., title="Optional callback that is invoked at the start of each training step")
# fmt: on
class Config:
@@ -424,7 +459,7 @@ class ProjectConfigAssetURL(BaseModel):
# fmt: off
dest: StrictStr = Field(..., title="Destination of downloaded asset")
url: Optional[StrictStr] = Field(None, title="URL of asset")
- checksum: str = Field(None, title="MD5 hash of file", regex=r"([a-fA-F\d]{32})")
+ checksum: Optional[str] = Field(None, title="MD5 hash of file", regex=r"([a-fA-F\d]{32})")
description: StrictStr = Field("", title="Description of asset")
# fmt: on
@@ -432,7 +467,7 @@ class ProjectConfigAssetURL(BaseModel):
class ProjectConfigAssetGit(BaseModel):
# fmt: off
git: ProjectConfigAssetGitItem = Field(..., title="Git repo information")
- checksum: str = Field(None, title="MD5 hash of file", regex=r"([a-fA-F\d]{32})")
+ checksum: Optional[str] = Field(None, title="MD5 hash of file", regex=r"([a-fA-F\d]{32})")
description: Optional[StrictStr] = Field(None, title="Description of asset")
# fmt: on
@@ -485,3 +520,37 @@ class RecommendationSchema(BaseModel):
word_vectors: Optional[str] = None
transformer: Optional[RecommendationTrf] = None
has_letters: bool = True
+
+
+class DocJSONSchema(BaseModel):
+ """
+ JSON/dict format for JSON representation of Doc objects.
+ """
+
+ cats: Optional[Dict[StrictStr, StrictFloat]] = Field(
+ None, title="Categories with corresponding probabilities"
+ )
+ ents: Optional[List[Dict[StrictStr, Union[StrictInt, StrictStr]]]] = Field(
+ None, title="Information on entities"
+ )
+ sents: Optional[List[Dict[StrictStr, StrictInt]]] = Field(
+ None, title="Indices of sentences' start and end indices"
+ )
+ text: StrictStr = Field(..., title="Document text")
+ spans: Optional[
+ Dict[StrictStr, List[Dict[StrictStr, Union[StrictStr, StrictInt]]]]
+ ] = Field(None, title="Span information - end/start indices, label, KB ID")
+ tokens: List[Dict[StrictStr, Union[StrictStr, StrictInt]]] = Field(
+ ..., title="Token information - ID, start, annotations"
+ )
+ underscore_doc: Optional[Dict[StrictStr, Any]] = Field(
+ None,
+ title="Any custom data stored in the document's _ attribute",
+ alias="_",
+ )
+ underscore_token: Optional[Dict[StrictStr, List[Dict[StrictStr, Any]]]] = Field(
+ None, title="Any custom data stored in the token's _ attribute"
+ )
+ underscore_span: Optional[Dict[StrictStr, List[Dict[StrictStr, Any]]]] = Field(
+ None, title="Any custom data stored in the span's _ attribute"
+ )
diff --git a/spacy/scorer.py b/spacy/scorer.py
index ae9338bd5..de4f52be6 100644
--- a/spacy/scorer.py
+++ b/spacy/scorer.py
@@ -174,7 +174,7 @@ class Scorer:
prf_score.score_set(pred_spans, gold_spans)
if len(acc_score) > 0:
return {
- "token_acc": acc_score.fscore,
+ "token_acc": acc_score.precision,
"token_p": prf_score.precision,
"token_r": prf_score.recall,
"token_f": prf_score.fscore,
@@ -228,7 +228,7 @@ class Scorer:
if token.orth_.isspace():
continue
if align.x2y.lengths[token.i] == 1:
- gold_i = align.x2y[token.i].dataXd[0, 0]
+ gold_i = align.x2y[token.i][0]
if gold_i not in missing_indices:
pred_tags.add((gold_i, getter(token, attr)))
tag_score.score_set(pred_tags, gold_tags)
@@ -287,7 +287,7 @@ class Scorer:
if token.orth_.isspace():
continue
if align.x2y.lengths[token.i] == 1:
- gold_i = align.x2y[token.i].dataXd[0, 0]
+ gold_i = align.x2y[token.i][0]
if gold_i not in missing_indices:
value = getter(token, attr)
morph = gold_doc.vocab.strings[value]
@@ -446,7 +446,7 @@ class Scorer:
labels (Iterable[str]): The set of possible labels. Defaults to [].
multi_label (bool): Whether the attribute allows multiple labels.
Defaults to True. When set to False (exclusive labels), missing
- gold labels are interpreted as 0.0.
+ gold labels are interpreted as 0.0 and the threshold is set to 0.0.
positive_label (str): The positive label for a binary task with
exclusive classes. Defaults to None.
threshold (float): Cutoff to consider a prediction "positive". Defaults
@@ -471,17 +471,17 @@ class Scorer:
"""
if threshold is None:
threshold = 0.5 if multi_label else 0.0
+ if not multi_label:
+ threshold = 0.0
f_per_type = {label: PRFScore() for label in labels}
auc_per_type = {label: ROCAUCScore() for label in labels}
labels = set(labels)
- if labels:
- for eg in examples:
- labels.update(eg.predicted.cats.keys())
- labels.update(eg.reference.cats.keys())
for example in examples:
# Through this loop, None in the gold_cats indicates missing label.
pred_cats = getter(example.predicted, attr)
+ pred_cats = {k: v for k, v in pred_cats.items() if k in labels}
gold_cats = getter(example.reference, attr)
+ gold_cats = {k: v for k, v in gold_cats.items() if k in labels}
for label in labels:
pred_score = pred_cats.get(label, 0.0)
@@ -505,20 +505,18 @@ class Scorer:
# Get the highest-scoring for each.
pred_label, pred_score = max(pred_cats.items(), key=lambda it: it[1])
gold_label, gold_score = max(gold_cats.items(), key=lambda it: it[1])
- if pred_label == gold_label and pred_score >= threshold:
+ if pred_label == gold_label:
f_per_type[pred_label].tp += 1
else:
f_per_type[gold_label].fn += 1
- if pred_score >= threshold:
- f_per_type[pred_label].fp += 1
+ f_per_type[pred_label].fp += 1
elif gold_cats:
gold_label, gold_score = max(gold_cats, key=lambda it: it[1])
if gold_score > 0:
f_per_type[gold_label].fn += 1
elif pred_cats:
pred_label, pred_score = max(pred_cats.items(), key=lambda it: it[1])
- if pred_score >= threshold:
- f_per_type[pred_label].fp += 1
+ f_per_type[pred_label].fp += 1
micro_prf = PRFScore()
for label_prf in f_per_type.values():
micro_prf.tp += label_prf.tp
@@ -694,13 +692,13 @@ class Scorer:
if align.x2y.lengths[token.i] != 1:
gold_i = None # type: ignore
else:
- gold_i = align.x2y[token.i].dataXd[0, 0]
+ gold_i = align.x2y[token.i][0]
if gold_i not in missing_indices:
dep = getter(token, attr)
head = head_getter(token, head_attr)
if dep not in ignore_labels and token.orth_.strip():
if align.x2y.lengths[head.i] == 1:
- gold_head = align.x2y[head.i].dataXd[0, 0]
+ gold_head = align.x2y[head.i][0]
else:
gold_head = None
# None is indistinct, so we can't just add it to the set
@@ -750,7 +748,7 @@ def get_ner_prf(examples: Iterable[Example], **kwargs) -> Dict[str, Any]:
for pred_ent in eg.x.ents:
if pred_ent.label_ not in score_per_type:
score_per_type[pred_ent.label_] = PRFScore()
- indices = align_x2y[pred_ent.start : pred_ent.end].dataXd.ravel()
+ indices = align_x2y[pred_ent.start : pred_ent.end]
if len(indices):
g_span = eg.y[indices[0] : indices[-1] + 1]
# Check we aren't missing annotation on this span. If so,
diff --git a/spacy/strings.pxd b/spacy/strings.pxd
index 370180135..5f03a9a28 100644
--- a/spacy/strings.pxd
+++ b/spacy/strings.pxd
@@ -26,4 +26,4 @@ cdef class StringStore:
cdef public PreshMap _map
cdef const Utf8Str* intern_unicode(self, str py_string)
- cdef const Utf8Str* _intern_utf8(self, char* utf8_string, int length)
+ cdef const Utf8Str* _intern_utf8(self, char* utf8_string, int length, hash_t* precalculated_hash)
diff --git a/spacy/strings.pyi b/spacy/strings.pyi
index 5b4147e12..b29389b9a 100644
--- a/spacy/strings.pyi
+++ b/spacy/strings.pyi
@@ -1,4 +1,4 @@
-from typing import Optional, Iterable, Iterator, Union, Any
+from typing import Optional, Iterable, Iterator, Union, Any, overload
from pathlib import Path
def get_string_id(key: Union[str, int]) -> int: ...
@@ -7,7 +7,10 @@ class StringStore:
def __init__(
self, strings: Optional[Iterable[str]] = ..., freeze: bool = ...
) -> None: ...
- def __getitem__(self, string_or_id: Union[bytes, str, int]) -> Union[str, int]: ...
+ @overload
+ def __getitem__(self, string_or_id: Union[bytes, str]) -> int: ...
+ @overload
+ def __getitem__(self, string_or_id: int) -> str: ...
def as_int(self, key: Union[bytes, str, int]) -> int: ...
def as_string(self, key: Union[bytes, str, int]) -> str: ...
def add(self, string: str) -> int: ...
diff --git a/spacy/strings.pyx b/spacy/strings.pyx
index 39fc441e9..c5f218342 100644
--- a/spacy/strings.pyx
+++ b/spacy/strings.pyx
@@ -14,6 +14,13 @@ from .symbols import NAMES as SYMBOLS_BY_INT
from .errors import Errors
from . import util
+# Not particularly elegant, but this is faster than `isinstance(key, numbers.Integral)`
+cdef inline bint _try_coerce_to_hash(object key, hash_t* out_hash):
+ try:
+ out_hash[0] = key
+ return True
+ except:
+ return False
def get_string_id(key):
"""Get a string ID, handling the reserved symbols correctly. If the key is
@@ -22,15 +29,27 @@ def get_string_id(key):
This function optimises for convenience over performance, so shouldn't be
used in tight loops.
"""
- if not isinstance(key, str):
- return key
- elif key in SYMBOLS_BY_STR:
- return SYMBOLS_BY_STR[key]
- elif not key:
- return 0
+ cdef hash_t str_hash
+ if isinstance(key, str):
+ if len(key) == 0:
+ return 0
+
+ symbol = SYMBOLS_BY_STR.get(key, None)
+ if symbol is not None:
+ return symbol
+ else:
+ chars = key.encode("utf8")
+ return hash_utf8(chars, len(chars))
+ elif _try_coerce_to_hash(key, &str_hash):
+ # Coerce the integral key to the expected primitive hash type.
+ # This ensures that custom/overloaded "primitive" data types
+ # such as those implemented by numpy are not inadvertently used
+ # downsteam (as these are internally implemented as custom PyObjects
+ # whose comparison operators can incur a significant overhead).
+ return str_hash
else:
- chars = key.encode("utf8")
- return hash_utf8(chars, len(chars))
+ # TODO: Raise an error instead
+ return key
cpdef hash_t hash_string(str string) except 0:
@@ -110,28 +129,36 @@ cdef class StringStore:
string_or_id (bytes, str or uint64): The value to encode.
Returns (str / uint64): The value to be retrieved.
"""
- if isinstance(string_or_id, str) and len(string_or_id) == 0:
- return 0
- elif string_or_id == 0:
- return ""
- elif string_or_id in SYMBOLS_BY_STR:
- return SYMBOLS_BY_STR[string_or_id]
- cdef hash_t key
+ cdef hash_t str_hash
+ cdef Utf8Str* utf8str = NULL
+
if isinstance(string_or_id, str):
- key = hash_string(string_or_id)
- return key
- elif isinstance(string_or_id, bytes):
- key = hash_utf8(string_or_id, len(string_or_id))
- return key
- elif string_or_id < len(SYMBOLS_BY_INT):
- return SYMBOLS_BY_INT[string_or_id]
- else:
- key = string_or_id
- utf8str = self._map.get(key)
- if utf8str is NULL:
- raise KeyError(Errors.E018.format(hash_value=string_or_id))
+ if len(string_or_id) == 0:
+ return 0
+
+ # Return early if the string is found in the symbols LUT.
+ symbol = SYMBOLS_BY_STR.get(string_or_id, None)
+ if symbol is not None:
+ return symbol
else:
- return decode_Utf8Str(utf8str)
+ return hash_string(string_or_id)
+ elif isinstance(string_or_id, bytes):
+ return hash_utf8(string_or_id, len(string_or_id))
+ elif _try_coerce_to_hash(string_or_id, &str_hash):
+ if str_hash == 0:
+ return ""
+ elif str_hash < len(SYMBOLS_BY_INT):
+ return SYMBOLS_BY_INT[str_hash]
+ else:
+ utf8str = self._map.get(str_hash)
+ else:
+ # TODO: Raise an error instead
+ utf8str = self._map.get(string_or_id)
+
+ if utf8str is NULL:
+ raise KeyError(Errors.E018.format(hash_value=string_or_id))
+ else:
+ return decode_Utf8Str(utf8str)
def as_int(self, key):
"""If key is an int, return it; otherwise, get the int value."""
@@ -153,19 +180,22 @@ cdef class StringStore:
string (str): The string to add.
RETURNS (uint64): The string's hash value.
"""
+ cdef hash_t str_hash
if isinstance(string, str):
if string in SYMBOLS_BY_STR:
return SYMBOLS_BY_STR[string]
- key = hash_string(string)
- self.intern_unicode(string)
+
+ string = string.encode("utf8")
+ str_hash = hash_utf8(string, len(string))
+ self._intern_utf8(string, len(string), &str_hash)
elif isinstance(string, bytes):
if string in SYMBOLS_BY_STR:
return SYMBOLS_BY_STR[string]
- key = hash_utf8(string, len(string))
- self._intern_utf8(string, len(string))
+ str_hash = hash_utf8(string, len(string))
+ self._intern_utf8(string, len(string), &str_hash)
else:
raise TypeError(Errors.E017.format(value_type=type(string)))
- return key
+ return str_hash
def __len__(self):
"""The number of strings in the store.
@@ -174,30 +204,29 @@ cdef class StringStore:
"""
return self.keys.size()
- def __contains__(self, string not None):
- """Check whether a string is in the store.
+ def __contains__(self, string_or_id not None):
+ """Check whether a string or ID is in the store.
- string (str): The string to check.
+ string_or_id (str or int): The string to check.
RETURNS (bool): Whether the store contains the string.
"""
- cdef hash_t key
- if isinstance(string, int) or isinstance(string, long):
- if string == 0:
+ cdef hash_t str_hash
+ if isinstance(string_or_id, str):
+ if len(string_or_id) == 0:
return True
- key = string
- elif len(string) == 0:
- return True
- elif string in SYMBOLS_BY_STR:
- return True
- elif isinstance(string, str):
- key = hash_string(string)
+ elif string_or_id in SYMBOLS_BY_STR:
+ return True
+ str_hash = hash_string(string_or_id)
+ elif _try_coerce_to_hash(string_or_id, &str_hash):
+ pass
else:
- string = string.encode("utf8")
- key = hash_utf8(string, len(string))
- if key < len(SYMBOLS_BY_INT):
+ # TODO: Raise an error instead
+ return self._map.get(string_or_id) is not NULL
+
+ if str_hash < len(SYMBOLS_BY_INT):
return True
else:
- return self._map.get(key) is not NULL
+ return self._map.get(str_hash) is not NULL
def __iter__(self):
"""Iterate over the strings in the store, in order.
@@ -272,13 +301,13 @@ cdef class StringStore:
cdef const Utf8Str* intern_unicode(self, str py_string):
# 0 means missing, but we don't bother offsetting the index.
cdef bytes byte_string = py_string.encode("utf8")
- return self._intern_utf8(byte_string, len(byte_string))
+ return self._intern_utf8(byte_string, len(byte_string), NULL)
@cython.final
- cdef const Utf8Str* _intern_utf8(self, char* utf8_string, int length):
+ cdef const Utf8Str* _intern_utf8(self, char* utf8_string, int length, hash_t* precalculated_hash):
# TODO: This function's API/behaviour is an unholy mess...
# 0 means missing, but we don't bother offsetting the index.
- cdef hash_t key = hash_utf8(utf8_string, length)
+ cdef hash_t key = precalculated_hash[0] if precalculated_hash is not NULL else hash_utf8(utf8_string, length)
cdef Utf8Str* value = self._map.get(key)
if value is not NULL:
return value
diff --git a/spacy/tests/conftest.py b/spacy/tests/conftest.py
index bca3cab1b..f8540b4c0 100644
--- a/spacy/tests/conftest.py
+++ b/spacy/tests/conftest.py
@@ -2,6 +2,12 @@ import pytest
from spacy.util import get_lang_class
from spacy.lang.en import English
from spacy.tokens import Doc
+from hypothesis import settings
+
+# Functionally disable deadline settings for tests
+# to prevent spurious test failures in CI builds.
+settings.register_profile("no_deadlines", deadline=2 * 60 * 1000) # in ms
+settings.load_profile("no_deadlines")
def pytest_addoption(parser):
@@ -101,6 +107,11 @@ def de_vocab():
return get_lang_class("de")().vocab
+@pytest.fixture(scope="session")
+def dsb_tokenizer():
+ return get_lang_class("dsb")().tokenizer
+
+
@pytest.fixture(scope="session")
def el_tokenizer():
return get_lang_class("el")().tokenizer
@@ -223,6 +234,11 @@ def ja_tokenizer():
return get_lang_class("ja")().tokenizer
+@pytest.fixture(scope="session")
+def hsb_tokenizer():
+ return get_lang_class("hsb")().tokenizer
+
+
@pytest.fixture(scope="session")
def ko_tokenizer():
pytest.importorskip("natto")
@@ -242,11 +258,21 @@ def ko_tokenizer_tokenizer():
return nlp.tokenizer
+@pytest.fixture(scope="module")
+def la_tokenizer():
+ return get_lang_class("la")().tokenizer
+
+
@pytest.fixture(scope="session")
def lb_tokenizer():
return get_lang_class("lb")().tokenizer
+@pytest.fixture(scope="session")
+def lg_tokenizer():
+ return get_lang_class("lg")().tokenizer
+
+
@pytest.fixture(scope="session")
def lt_tokenizer():
return get_lang_class("lt")().tokenizer
@@ -314,16 +340,24 @@ def ro_tokenizer():
@pytest.fixture(scope="session")
def ru_tokenizer():
- pytest.importorskip("pymorphy2")
+ pytest.importorskip("pymorphy3")
return get_lang_class("ru")().tokenizer
-@pytest.fixture
+@pytest.fixture(scope="session")
def ru_lemmatizer():
- pytest.importorskip("pymorphy2")
+ pytest.importorskip("pymorphy3")
return get_lang_class("ru")().add_pipe("lemmatizer")
+@pytest.fixture(scope="session")
+def ru_lookup_lemmatizer():
+ pytest.importorskip("pymorphy3")
+ return get_lang_class("ru")().add_pipe(
+ "lemmatizer", config={"mode": "pymorphy3_lookup"}
+ )
+
+
@pytest.fixture(scope="session")
def sa_tokenizer():
return get_lang_class("sa")().tokenizer
@@ -354,6 +388,11 @@ def sv_tokenizer():
return get_lang_class("sv")().tokenizer
+@pytest.fixture(scope="session")
+def ta_tokenizer():
+ return get_lang_class("ta")().tokenizer
+
+
@pytest.fixture(scope="session")
def th_tokenizer():
pytest.importorskip("pythainlp")
@@ -387,17 +426,26 @@ def ky_tokenizer():
@pytest.fixture(scope="session")
def uk_tokenizer():
- pytest.importorskip("pymorphy2")
+ pytest.importorskip("pymorphy3")
return get_lang_class("uk")().tokenizer
-@pytest.fixture
+@pytest.fixture(scope="session")
def uk_lemmatizer():
- pytest.importorskip("pymorphy2")
- pytest.importorskip("pymorphy2_dicts_uk")
+ pytest.importorskip("pymorphy3")
+ pytest.importorskip("pymorphy3_dicts_uk")
return get_lang_class("uk")().add_pipe("lemmatizer")
+@pytest.fixture(scope="session")
+def uk_lookup_lemmatizer():
+ pytest.importorskip("pymorphy3")
+ pytest.importorskip("pymorphy3_dicts_uk")
+ return get_lang_class("uk")().add_pipe(
+ "lemmatizer", config={"mode": "pymorphy3_lookup"}
+ )
+
+
@pytest.fixture(scope="session")
def ur_tokenizer():
return get_lang_class("ur")().tokenizer
diff --git a/spacy/tests/doc/test_array.py b/spacy/tests/doc/test_array.py
index c334cc6eb..1f2d7d999 100644
--- a/spacy/tests/doc/test_array.py
+++ b/spacy/tests/doc/test_array.py
@@ -123,14 +123,14 @@ def test_doc_from_array_heads_in_bounds(en_vocab):
# head before start
arr = doc.to_array(["HEAD"])
- arr[0] = -1
+ arr[0] = numpy.int32(-1).astype(numpy.uint64)
doc_from_array = Doc(en_vocab, words=words)
with pytest.raises(ValueError):
doc_from_array.from_array(["HEAD"], arr)
# head after end
arr = doc.to_array(["HEAD"])
- arr[0] = 5
+ arr[0] = numpy.int32(5).astype(numpy.uint64)
doc_from_array = Doc(en_vocab, words=words)
with pytest.raises(ValueError):
doc_from_array.from_array(["HEAD"], arr)
diff --git a/spacy/tests/doc/test_doc_api.py b/spacy/tests/doc/test_doc_api.py
index 858c7cbb6..38003dea9 100644
--- a/spacy/tests/doc/test_doc_api.py
+++ b/spacy/tests/doc/test_doc_api.py
@@ -1,7 +1,9 @@
import weakref
import numpy
+from numpy.testing import assert_array_equal
import pytest
+import warnings
from thinc.api import NumpyOps, get_current_ops
from spacy.attrs import DEP, ENT_IOB, ENT_TYPE, HEAD, IS_ALPHA, MORPH, POS
@@ -10,7 +12,7 @@ from spacy.lang.en import English
from spacy.lang.xx import MultiLanguage
from spacy.language import Language
from spacy.lexeme import Lexeme
-from spacy.tokens import Doc, Span, Token
+from spacy.tokens import Doc, Span, SpanGroup, Token
from spacy.vocab import Vocab
from .test_underscore import clean_underscore # noqa: F401
@@ -80,6 +82,21 @@ def test_issue2396(en_vocab):
assert (span.get_lca_matrix() == matrix).all()
+@pytest.mark.issue(11499)
+def test_init_args_unmodified(en_vocab):
+ words = ["A", "sentence"]
+ ents = ["B-TYPE1", ""]
+ sent_starts = [True, False]
+ Doc(
+ vocab=en_vocab,
+ words=words,
+ ents=ents,
+ sent_starts=sent_starts,
+ )
+ assert ents == ["B-TYPE1", ""]
+ assert sent_starts == [True, False]
+
+
@pytest.mark.parametrize("text", ["-0.23", "+123,456", "±1"])
@pytest.mark.parametrize("lang_cls", [English, MultiLanguage])
@pytest.mark.issue(2782)
@@ -528,9 +545,9 @@ def test_doc_from_array_sent_starts(en_vocab):
# no warning using default attrs
attrs = doc._get_array_attrs()
arr = doc.to_array(attrs)
- with pytest.warns(None) as record:
+ with warnings.catch_warnings():
+ warnings.simplefilter("error")
new_doc.from_array(attrs, arr)
- assert len(record) == 0
# only SENT_START uses SENT_START
attrs = [SENT_START]
arr = doc.to_array(attrs)
@@ -634,6 +651,14 @@ def test_doc_api_from_docs(en_tokenizer, de_tokenizer):
assert "group" in m_doc.spans
assert span_group_texts == sorted([s.text for s in m_doc.spans["group"]])
+ # can exclude spans
+ m_doc = Doc.from_docs(en_docs, exclude=["spans"])
+ assert "group" not in m_doc.spans
+
+ # can exclude user_data
+ m_doc = Doc.from_docs(en_docs, exclude=["user_data"])
+ assert m_doc.user_data == {}
+
# can merge empty docs
doc = Doc.from_docs([en_tokenizer("")] * 10)
@@ -647,6 +672,20 @@ def test_doc_api_from_docs(en_tokenizer, de_tokenizer):
assert "group" in m_doc.spans
assert len(m_doc.spans["group"]) == 0
+ # with tensor
+ ops = get_current_ops()
+ for doc in en_docs:
+ doc.tensor = ops.asarray([[len(t.text), 0.0] for t in doc])
+ m_doc = Doc.from_docs(en_docs)
+ assert_array_equal(
+ ops.to_numpy(m_doc.tensor),
+ ops.to_numpy(ops.xp.vstack([doc.tensor for doc in en_docs if len(doc)])),
+ )
+
+ # can exclude tensor
+ m_doc = Doc.from_docs(en_docs, exclude=["tensor"])
+ assert m_doc.tensor.shape == (0,)
+
def test_doc_api_from_docs_ents(en_tokenizer):
texts = ["Merging the docs is fun.", "They don't think alike."]
@@ -941,3 +980,13 @@ def test_doc_spans_copy(en_tokenizer):
assert weakref.ref(doc1) == doc1.spans.doc_ref
doc2 = doc1.copy()
assert weakref.ref(doc2) == doc2.spans.doc_ref
+
+
+def test_doc_spans_setdefault(en_tokenizer):
+ doc = en_tokenizer("Some text about Colombia and the Czech Republic")
+ doc.spans.setdefault("key1")
+ assert len(doc.spans["key1"]) == 0
+ doc.spans.setdefault("key2", default=[doc[0:1]])
+ assert len(doc.spans["key2"]) == 1
+ doc.spans.setdefault("key3", default=SpanGroup(doc, spans=[doc[0:1], doc[1:2]]))
+ assert len(doc.spans["key3"]) == 2
diff --git a/spacy/tests/doc/test_json_doc_conversion.py b/spacy/tests/doc/test_json_doc_conversion.py
new file mode 100644
index 000000000..11a1817e6
--- /dev/null
+++ b/spacy/tests/doc/test_json_doc_conversion.py
@@ -0,0 +1,381 @@
+import pytest
+import spacy
+from spacy import schemas
+from spacy.tokens import Doc, Span, Token
+import srsly
+from .test_underscore import clean_underscore # noqa: F401
+
+
+@pytest.fixture()
+def doc(en_vocab):
+ words = ["c", "d", "e"]
+ spaces = [True, True, True]
+ pos = ["VERB", "NOUN", "NOUN"]
+ tags = ["VBP", "NN", "NN"]
+ heads = [0, 0, 1]
+ deps = ["ROOT", "dobj", "dobj"]
+ ents = ["O", "B-ORG", "O"]
+ morphs = ["Feat1=A", "Feat1=B", "Feat1=A|Feat2=D"]
+
+ return Doc(
+ en_vocab,
+ words=words,
+ spaces=spaces,
+ pos=pos,
+ tags=tags,
+ heads=heads,
+ deps=deps,
+ ents=ents,
+ morphs=morphs,
+ )
+
+
+@pytest.fixture()
+def doc_without_deps(en_vocab):
+ words = ["c", "d", "e"]
+ pos = ["VERB", "NOUN", "NOUN"]
+ tags = ["VBP", "NN", "NN"]
+ ents = ["O", "B-ORG", "O"]
+ morphs = ["Feat1=A", "Feat1=B", "Feat1=A|Feat2=D"]
+
+ return Doc(
+ en_vocab,
+ words=words,
+ pos=pos,
+ tags=tags,
+ ents=ents,
+ morphs=morphs,
+ sent_starts=[True, False, True],
+ )
+
+
+@pytest.fixture()
+def doc_json():
+ return {
+ "text": "c d e ",
+ "ents": [{"start": 2, "end": 3, "label": "ORG"}],
+ "sents": [{"start": 0, "end": 5}],
+ "tokens": [
+ {
+ "id": 0,
+ "start": 0,
+ "end": 1,
+ "tag": "VBP",
+ "pos": "VERB",
+ "morph": "Feat1=A",
+ "dep": "ROOT",
+ "head": 0,
+ },
+ {
+ "id": 1,
+ "start": 2,
+ "end": 3,
+ "tag": "NN",
+ "pos": "NOUN",
+ "morph": "Feat1=B",
+ "dep": "dobj",
+ "head": 0,
+ },
+ {
+ "id": 2,
+ "start": 4,
+ "end": 5,
+ "tag": "NN",
+ "pos": "NOUN",
+ "morph": "Feat1=A|Feat2=D",
+ "dep": "dobj",
+ "head": 1,
+ },
+ ],
+ }
+
+
+def test_doc_to_json(doc):
+ json_doc = doc.to_json()
+ assert json_doc["text"] == "c d e "
+ assert len(json_doc["tokens"]) == 3
+ assert json_doc["tokens"][0]["pos"] == "VERB"
+ assert json_doc["tokens"][0]["tag"] == "VBP"
+ assert json_doc["tokens"][0]["dep"] == "ROOT"
+ assert len(json_doc["ents"]) == 1
+ assert json_doc["ents"][0]["start"] == 2 # character offset!
+ assert json_doc["ents"][0]["end"] == 3 # character offset!
+ assert json_doc["ents"][0]["label"] == "ORG"
+ assert len(schemas.validate(schemas.DocJSONSchema, json_doc)) == 0
+ assert srsly.json_loads(srsly.json_dumps(json_doc)) == json_doc
+
+
+def test_doc_to_json_underscore(doc):
+ Doc.set_extension("json_test1", default=False)
+ Doc.set_extension("json_test2", default=False)
+ doc._.json_test1 = "hello world"
+ doc._.json_test2 = [1, 2, 3]
+
+ json_doc = doc.to_json(underscore=["json_test1", "json_test2"])
+ assert "_" in json_doc
+ assert json_doc["_"]["json_test1"] == "hello world"
+ assert json_doc["_"]["json_test2"] == [1, 2, 3]
+ assert len(schemas.validate(schemas.DocJSONSchema, json_doc)) == 0
+ assert srsly.json_loads(srsly.json_dumps(json_doc)) == json_doc
+
+
+def test_doc_to_json_with_token_span_attributes(doc):
+ Doc.set_extension("json_test1", default=False)
+ Doc.set_extension("json_test2", default=False)
+ Token.set_extension("token_test", default=False)
+ Span.set_extension("span_test", default=False)
+
+ doc._.json_test1 = "hello world"
+ doc._.json_test2 = [1, 2, 3]
+ doc[0:1]._.span_test = "span_attribute"
+ doc[0:2]._.span_test = "span_attribute_2"
+ doc[0]._.token_test = 117
+ doc[1]._.token_test = 118
+ doc.spans["span_group"] = [doc[0:1]]
+ json_doc = doc.to_json(
+ underscore=["json_test1", "json_test2", "token_test", "span_test"]
+ )
+
+ assert "_" in json_doc
+ assert json_doc["_"]["json_test1"] == "hello world"
+ assert json_doc["_"]["json_test2"] == [1, 2, 3]
+ assert "underscore_token" in json_doc
+ assert "underscore_span" in json_doc
+ assert json_doc["underscore_token"]["token_test"][0]["value"] == 117
+ assert json_doc["underscore_token"]["token_test"][1]["value"] == 118
+ assert json_doc["underscore_span"]["span_test"][0]["value"] == "span_attribute"
+ assert json_doc["underscore_span"]["span_test"][1]["value"] == "span_attribute_2"
+ assert len(schemas.validate(schemas.DocJSONSchema, json_doc)) == 0
+ assert srsly.json_loads(srsly.json_dumps(json_doc)) == json_doc
+
+
+def test_doc_to_json_with_custom_user_data(doc):
+ Doc.set_extension("json_test", default=False)
+ Token.set_extension("token_test", default=False)
+ Span.set_extension("span_test", default=False)
+
+ doc._.json_test = "hello world"
+ doc[0:1]._.span_test = "span_attribute"
+ doc[0]._.token_test = 117
+ json_doc = doc.to_json(underscore=["json_test", "token_test", "span_test"])
+ doc.user_data["user_data_test"] = 10
+ doc.user_data[("user_data_test2", True)] = 10
+
+ assert "_" in json_doc
+ assert json_doc["_"]["json_test"] == "hello world"
+ assert "underscore_token" in json_doc
+ assert "underscore_span" in json_doc
+ assert json_doc["underscore_token"]["token_test"][0]["value"] == 117
+ assert json_doc["underscore_span"]["span_test"][0]["value"] == "span_attribute"
+ assert len(schemas.validate(schemas.DocJSONSchema, json_doc)) == 0
+ assert srsly.json_loads(srsly.json_dumps(json_doc)) == json_doc
+
+
+def test_doc_to_json_with_token_span_same_identifier(doc):
+ Doc.set_extension("my_ext", default=False)
+ Token.set_extension("my_ext", default=False)
+ Span.set_extension("my_ext", default=False)
+
+ doc._.my_ext = "hello world"
+ doc[0:1]._.my_ext = "span_attribute"
+ doc[0]._.my_ext = 117
+ json_doc = doc.to_json(underscore=["my_ext"])
+
+ assert "_" in json_doc
+ assert json_doc["_"]["my_ext"] == "hello world"
+ assert "underscore_token" in json_doc
+ assert "underscore_span" in json_doc
+ assert json_doc["underscore_token"]["my_ext"][0]["value"] == 117
+ assert json_doc["underscore_span"]["my_ext"][0]["value"] == "span_attribute"
+ assert len(schemas.validate(schemas.DocJSONSchema, json_doc)) == 0
+ assert srsly.json_loads(srsly.json_dumps(json_doc)) == json_doc
+
+
+def test_doc_to_json_with_token_attributes_missing(doc):
+ Token.set_extension("token_test", default=False)
+ Span.set_extension("span_test", default=False)
+
+ doc[0:1]._.span_test = "span_attribute"
+ doc[0]._.token_test = 117
+ json_doc = doc.to_json(underscore=["span_test"])
+
+ assert "underscore_span" in json_doc
+ assert json_doc["underscore_span"]["span_test"][0]["value"] == "span_attribute"
+ assert "underscore_token" not in json_doc
+ assert len(schemas.validate(schemas.DocJSONSchema, json_doc)) == 0
+
+
+def test_doc_to_json_underscore_error_attr(doc):
+ """Test that Doc.to_json() raises an error if a custom attribute doesn't
+ exist in the ._ space."""
+ with pytest.raises(ValueError):
+ doc.to_json(underscore=["json_test3"])
+
+
+def test_doc_to_json_underscore_error_serialize(doc):
+ """Test that Doc.to_json() raises an error if a custom attribute value
+ isn't JSON-serializable."""
+ Doc.set_extension("json_test4", method=lambda doc: doc.text)
+ with pytest.raises(ValueError):
+ doc.to_json(underscore=["json_test4"])
+
+
+def test_doc_to_json_span(doc):
+ """Test that Doc.to_json() includes spans"""
+ doc.spans["test"] = [Span(doc, 0, 2, "test"), Span(doc, 0, 1, "test")]
+ json_doc = doc.to_json()
+ assert "spans" in json_doc
+ assert len(json_doc["spans"]) == 1
+ assert len(json_doc["spans"]["test"]) == 2
+ assert json_doc["spans"]["test"][0]["start"] == 0
+ assert len(schemas.validate(schemas.DocJSONSchema, json_doc)) == 0
+
+
+def test_json_to_doc(doc):
+ json_doc = doc.to_json()
+ json_doc = srsly.json_loads(srsly.json_dumps(json_doc))
+ new_doc = Doc(doc.vocab).from_json(json_doc, validate=True)
+ assert new_doc.text == doc.text == "c d e "
+ assert len(new_doc) == len(doc) == 3
+ assert new_doc[0].pos == doc[0].pos
+ assert new_doc[0].tag == doc[0].tag
+ assert new_doc[0].dep == doc[0].dep
+ assert new_doc[0].head.idx == doc[0].head.idx
+ assert new_doc[0].lemma == doc[0].lemma
+ assert len(new_doc.ents) == 1
+ assert new_doc.ents[0].start == 1
+ assert new_doc.ents[0].end == 2
+ assert new_doc.ents[0].label_ == "ORG"
+ assert doc.to_bytes() == new_doc.to_bytes()
+
+
+def test_json_to_doc_compat(doc, doc_json):
+ new_doc = Doc(doc.vocab).from_json(doc_json, validate=True)
+ new_tokens = [token for token in new_doc]
+ assert new_doc.text == doc.text == "c d e "
+ assert len(new_tokens) == len([token for token in doc]) == 3
+ assert new_tokens[0].pos == doc[0].pos
+ assert new_tokens[0].tag == doc[0].tag
+ assert new_tokens[0].dep == doc[0].dep
+ assert new_tokens[0].head.idx == doc[0].head.idx
+ assert new_tokens[0].lemma == doc[0].lemma
+ assert len(new_doc.ents) == 1
+ assert new_doc.ents[0].start == 1
+ assert new_doc.ents[0].end == 2
+ assert new_doc.ents[0].label_ == "ORG"
+
+
+def test_json_to_doc_underscore(doc):
+ Doc.set_extension("json_test1", default=False)
+ Doc.set_extension("json_test2", default=False)
+ doc._.json_test1 = "hello world"
+ doc._.json_test2 = [1, 2, 3]
+ json_doc = doc.to_json(underscore=["json_test1", "json_test2"])
+ new_doc = Doc(doc.vocab).from_json(json_doc, validate=True)
+ assert all([new_doc.has_extension(f"json_test{i}") for i in range(1, 3)])
+ assert new_doc._.json_test1 == "hello world"
+ assert new_doc._.json_test2 == [1, 2, 3]
+ assert doc.to_bytes() == new_doc.to_bytes()
+
+
+def test_json_to_doc_with_token_span_attributes(doc):
+ Doc.set_extension("json_test1", default=False)
+ Doc.set_extension("json_test2", default=False)
+ Token.set_extension("token_test", default=False)
+ Span.set_extension("span_test", default=False)
+ doc._.json_test1 = "hello world"
+ doc._.json_test2 = [1, 2, 3]
+ doc[0:1]._.span_test = "span_attribute"
+ doc[0:2]._.span_test = "span_attribute_2"
+ doc[0]._.token_test = 117
+ doc[1]._.token_test = 118
+
+ json_doc = doc.to_json(
+ underscore=["json_test1", "json_test2", "token_test", "span_test"]
+ )
+ json_doc = srsly.json_loads(srsly.json_dumps(json_doc))
+ new_doc = Doc(doc.vocab).from_json(json_doc, validate=True)
+
+ assert all([new_doc.has_extension(f"json_test{i}") for i in range(1, 3)])
+ assert new_doc._.json_test1 == "hello world"
+ assert new_doc._.json_test2 == [1, 2, 3]
+ assert new_doc[0]._.token_test == 117
+ assert new_doc[1]._.token_test == 118
+ assert new_doc[0:1]._.span_test == "span_attribute"
+ assert new_doc[0:2]._.span_test == "span_attribute_2"
+ assert new_doc.user_data == doc.user_data
+ assert new_doc.to_bytes(exclude=["user_data"]) == doc.to_bytes(
+ exclude=["user_data"]
+ )
+
+
+def test_json_to_doc_spans(doc):
+ """Test that Doc.from_json() includes correct.spans."""
+ doc.spans["test"] = [
+ Span(doc, 0, 2, label="test"),
+ Span(doc, 0, 1, label="test", kb_id=7),
+ ]
+ json_doc = doc.to_json()
+ new_doc = Doc(doc.vocab).from_json(json_doc, validate=True)
+ assert len(new_doc.spans) == 1
+ assert len(new_doc.spans["test"]) == 2
+ for i in range(2):
+ assert new_doc.spans["test"][i].start == doc.spans["test"][i].start
+ assert new_doc.spans["test"][i].end == doc.spans["test"][i].end
+ assert new_doc.spans["test"][i].label == doc.spans["test"][i].label
+ assert new_doc.spans["test"][i].kb_id == doc.spans["test"][i].kb_id
+
+
+def test_json_to_doc_sents(doc, doc_without_deps):
+ """Test that Doc.from_json() includes correct.sents."""
+ for test_doc in (doc, doc_without_deps):
+ json_doc = test_doc.to_json()
+ new_doc = Doc(doc.vocab).from_json(json_doc, validate=True)
+ assert [sent.text for sent in test_doc.sents] == [
+ sent.text for sent in new_doc.sents
+ ]
+ assert [token.is_sent_start for token in test_doc] == [
+ token.is_sent_start for token in new_doc
+ ]
+
+
+def test_json_to_doc_cats(doc):
+ """Test that Doc.from_json() includes correct .cats."""
+ cats = {"A": 0.3, "B": 0.7}
+ doc.cats = cats
+ json_doc = doc.to_json()
+ new_doc = Doc(doc.vocab).from_json(json_doc, validate=True)
+ assert new_doc.cats == cats
+
+
+def test_json_to_doc_spaces():
+ """Test that Doc.from_json() preserves spaces correctly."""
+ doc = spacy.blank("en")("This is just brilliant.")
+ json_doc = doc.to_json()
+ new_doc = Doc(doc.vocab).from_json(json_doc, validate=True)
+ assert doc.text == new_doc.text
+
+
+def test_json_to_doc_attribute_consistency(doc):
+ """Test that Doc.from_json() raises an exception if tokens don't all have the same set of properties."""
+ doc_json = doc.to_json()
+ doc_json["tokens"][1].pop("morph")
+ with pytest.raises(ValueError):
+ Doc(doc.vocab).from_json(doc_json)
+
+
+def test_json_to_doc_validation_error(doc):
+ """Test that Doc.from_json() raises an exception when validating invalid input."""
+ doc_json = doc.to_json()
+ doc_json.pop("tokens")
+ with pytest.raises(ValueError):
+ Doc(doc.vocab).from_json(doc_json, validate=True)
+
+
+def test_to_json_underscore_doc_getters(doc):
+ def get_text_length(doc):
+ return len(doc.text)
+
+ Doc.set_extension("text_length", getter=get_text_length)
+ doc_json = doc.to_json(underscore=["text_length"])
+ assert doc_json["_"]["text_length"] == get_text_length(doc)
diff --git a/spacy/tests/doc/test_pickle_doc.py b/spacy/tests/doc/test_pickle_doc.py
index 738a751a0..28cb66714 100644
--- a/spacy/tests/doc/test_pickle_doc.py
+++ b/spacy/tests/doc/test_pickle_doc.py
@@ -5,11 +5,9 @@ from spacy.compat import pickle
def test_pickle_single_doc():
nlp = Language()
doc = nlp("pickle roundtrip")
- doc._context = 3
data = pickle.dumps(doc, 1)
doc2 = pickle.loads(data)
assert doc2.text == "pickle roundtrip"
- assert doc2._context == 3
def test_list_of_docs_pickles_efficiently():
diff --git a/spacy/tests/doc/test_span.py b/spacy/tests/doc/test_span.py
index c0496cabf..3676b35af 100644
--- a/spacy/tests/doc/test_span.py
+++ b/spacy/tests/doc/test_span.py
@@ -428,10 +428,19 @@ def test_span_string_label_kb_id(doc):
assert span.kb_id == doc.vocab.strings["Q342"]
+def test_span_string_label_id(doc):
+ span = Span(doc, 0, 1, label="hello", span_id="Q342")
+ assert span.label_ == "hello"
+ assert span.label == doc.vocab.strings["hello"]
+ assert span.id_ == "Q342"
+ assert span.id == doc.vocab.strings["Q342"]
+
+
def test_span_attrs_writable(doc):
span = Span(doc, 0, 1)
span.label_ = "label"
span.kb_id_ = "kb_id"
+ span.id_ = "id"
def test_span_ents_property(doc):
@@ -619,6 +628,9 @@ def test_span_comparison(doc):
assert Span(doc, 0, 4, "LABEL", kb_id="KB_ID") <= Span(doc, 1, 3)
assert Span(doc, 1, 3) > Span(doc, 0, 4, "LABEL", kb_id="KB_ID")
assert Span(doc, 1, 3) >= Span(doc, 0, 4, "LABEL", kb_id="KB_ID")
+
+ # Different id
+ assert Span(doc, 1, 3, span_id="AAA") < Span(doc, 1, 3, span_id="BBB")
# fmt: on
diff --git a/spacy/tests/doc/test_span_group.py b/spacy/tests/doc/test_span_group.py
new file mode 100644
index 000000000..818569c64
--- /dev/null
+++ b/spacy/tests/doc/test_span_group.py
@@ -0,0 +1,255 @@
+from typing import List
+
+import pytest
+from random import Random
+from spacy.matcher import Matcher
+from spacy.tokens import Span, SpanGroup, Doc
+from spacy.util import filter_spans
+
+
+@pytest.fixture
+def doc(en_tokenizer):
+ doc = en_tokenizer("0 1 2 3 4 5 6")
+ matcher = Matcher(en_tokenizer.vocab, validate=True)
+
+ # fmt: off
+ matcher.add("4", [[{}, {}, {}, {}]])
+ matcher.add("2", [[{}, {}, ]])
+ matcher.add("1", [[{}, ]])
+ # fmt: on
+ matches = matcher(doc)
+ spans = []
+ for match in matches:
+ spans.append(
+ Span(doc, match[1], match[2], en_tokenizer.vocab.strings[match[0]])
+ )
+ Random(42).shuffle(spans)
+ doc.spans["SPANS"] = SpanGroup(
+ doc, name="SPANS", attrs={"key": "value"}, spans=spans
+ )
+ return doc
+
+
+@pytest.fixture
+def other_doc(en_tokenizer):
+ doc = en_tokenizer("0 1 2 3 4 5 6")
+ matcher = Matcher(en_tokenizer.vocab, validate=True)
+
+ # fmt: off
+ matcher.add("4", [[{}, {}, {}, {}]])
+ matcher.add("2", [[{}, {}, ]])
+ matcher.add("1", [[{}, ]])
+ # fmt: on
+
+ matches = matcher(doc)
+ spans = []
+ for match in matches:
+ spans.append(
+ Span(doc, match[1], match[2], en_tokenizer.vocab.strings[match[0]])
+ )
+ Random(42).shuffle(spans)
+ doc.spans["SPANS"] = SpanGroup(
+ doc, name="SPANS", attrs={"key": "value"}, spans=spans
+ )
+ return doc
+
+
+@pytest.fixture
+def span_group(en_tokenizer):
+ doc = en_tokenizer("0 1 2 3 4 5 6")
+ matcher = Matcher(en_tokenizer.vocab, validate=True)
+
+ # fmt: off
+ matcher.add("4", [[{}, {}, {}, {}]])
+ matcher.add("2", [[{}, {}, ]])
+ matcher.add("1", [[{}, ]])
+ # fmt: on
+
+ matches = matcher(doc)
+ spans = []
+ for match in matches:
+ spans.append(
+ Span(doc, match[1], match[2], en_tokenizer.vocab.strings[match[0]])
+ )
+ Random(42).shuffle(spans)
+ doc.spans["SPANS"] = SpanGroup(
+ doc, name="SPANS", attrs={"key": "value"}, spans=spans
+ )
+
+
+def test_span_group_copy(doc):
+ span_group = doc.spans["SPANS"]
+ clone = span_group.copy()
+ assert clone != span_group
+ assert clone.name == span_group.name
+ assert clone.attrs == span_group.attrs
+ assert len(clone) == len(span_group)
+ assert list(span_group) == list(clone)
+ clone.name = "new_name"
+ clone.attrs["key"] = "new_value"
+ clone.append(Span(doc, 0, 6, "LABEL"))
+ assert clone.name != span_group.name
+ assert clone.attrs != span_group.attrs
+ assert span_group.attrs["key"] == "value"
+ assert list(span_group) != list(clone)
+
+
+def test_span_group_set_item(doc, other_doc):
+ span_group = doc.spans["SPANS"]
+
+ index = 5
+ span = span_group[index]
+ span.label_ = "NEW LABEL"
+ span.kb_id = doc.vocab.strings["KB_ID"]
+
+ assert span_group[index].label != span.label
+ assert span_group[index].kb_id != span.kb_id
+
+ span_group[index] = span
+ assert span_group[index].start == span.start
+ assert span_group[index].end == span.end
+ assert span_group[index].label == span.label
+ assert span_group[index].kb_id == span.kb_id
+ assert span_group[index] == span
+
+ with pytest.raises(IndexError):
+ span_group[-100] = span
+ with pytest.raises(IndexError):
+ span_group[100] = span
+
+ span = Span(other_doc, 0, 2)
+ with pytest.raises(ValueError):
+ span_group[index] = span
+
+
+def test_span_group_has_overlap(doc):
+ span_group = doc.spans["SPANS"]
+ assert span_group.has_overlap
+
+
+def test_span_group_concat(doc, other_doc):
+ span_group_1 = doc.spans["SPANS"]
+ spans = [doc[0:5], doc[0:6]]
+ span_group_2 = SpanGroup(
+ doc,
+ name="MORE_SPANS",
+ attrs={"key": "new_value", "new_key": "new_value"},
+ spans=spans,
+ )
+ span_group_3 = span_group_1._concat(span_group_2)
+ assert span_group_3.name == span_group_1.name
+ assert span_group_3.attrs == {"key": "value", "new_key": "new_value"}
+ span_list_expected = list(span_group_1) + list(span_group_2)
+ assert list(span_group_3) == list(span_list_expected)
+
+ # Inplace
+ span_list_expected = list(span_group_1) + list(span_group_2)
+ span_group_3 = span_group_1._concat(span_group_2, inplace=True)
+ assert span_group_3 == span_group_1
+ assert span_group_3.name == span_group_1.name
+ assert span_group_3.attrs == {"key": "value", "new_key": "new_value"}
+ assert list(span_group_3) == list(span_list_expected)
+
+ span_group_2 = other_doc.spans["SPANS"]
+ with pytest.raises(ValueError):
+ span_group_1._concat(span_group_2)
+
+
+def test_span_doc_delitem(doc):
+ span_group = doc.spans["SPANS"]
+ length = len(span_group)
+ index = 5
+ span = span_group[index]
+ next_span = span_group[index + 1]
+ del span_group[index]
+ assert len(span_group) == length - 1
+ assert span_group[index] != span
+ assert span_group[index] == next_span
+
+ with pytest.raises(IndexError):
+ del span_group[-100]
+ with pytest.raises(IndexError):
+ del span_group[100]
+
+
+def test_span_group_add(doc):
+ span_group_1 = doc.spans["SPANS"]
+ spans = [doc[0:5], doc[0:6]]
+ span_group_2 = SpanGroup(
+ doc,
+ name="MORE_SPANS",
+ attrs={"key": "new_value", "new_key": "new_value"},
+ spans=spans,
+ )
+
+ span_group_3_expected = span_group_1._concat(span_group_2)
+
+ span_group_3 = span_group_1 + span_group_2
+ assert len(span_group_3) == len(span_group_3_expected)
+ assert span_group_3.attrs == {"key": "value", "new_key": "new_value"}
+ assert list(span_group_3) == list(span_group_3_expected)
+
+
+def test_span_group_iadd(doc):
+ span_group_1 = doc.spans["SPANS"].copy()
+ spans = [doc[0:5], doc[0:6]]
+ span_group_2 = SpanGroup(
+ doc,
+ name="MORE_SPANS",
+ attrs={"key": "new_value", "new_key": "new_value"},
+ spans=spans,
+ )
+
+ span_group_1_expected = span_group_1._concat(span_group_2)
+
+ span_group_1 += span_group_2
+ assert len(span_group_1) == len(span_group_1_expected)
+ assert span_group_1.attrs == {"key": "value", "new_key": "new_value"}
+ assert list(span_group_1) == list(span_group_1_expected)
+
+ span_group_1 = doc.spans["SPANS"].copy()
+ span_group_1 += spans
+ assert len(span_group_1) == len(span_group_1_expected)
+ assert span_group_1.attrs == {
+ "key": "value",
+ }
+ assert list(span_group_1) == list(span_group_1_expected)
+
+
+def test_span_group_extend(doc):
+ span_group_1 = doc.spans["SPANS"].copy()
+ spans = [doc[0:5], doc[0:6]]
+ span_group_2 = SpanGroup(
+ doc,
+ name="MORE_SPANS",
+ attrs={"key": "new_value", "new_key": "new_value"},
+ spans=spans,
+ )
+
+ span_group_1_expected = span_group_1._concat(span_group_2)
+
+ span_group_1.extend(span_group_2)
+ assert len(span_group_1) == len(span_group_1_expected)
+ assert span_group_1.attrs == {"key": "value", "new_key": "new_value"}
+ assert list(span_group_1) == list(span_group_1_expected)
+
+ span_group_1 = doc.spans["SPANS"]
+ span_group_1.extend(spans)
+ assert len(span_group_1) == len(span_group_1_expected)
+ assert span_group_1.attrs == {"key": "value"}
+ assert list(span_group_1) == list(span_group_1_expected)
+
+
+def test_span_group_dealloc(span_group):
+ with pytest.raises(AttributeError):
+ print(span_group.doc)
+
+
+@pytest.mark.issue(11975)
+def test_span_group_typing(doc: Doc):
+ """Tests whether typing of `SpanGroup` as `Iterable[Span]`-like object is accepted by mypy."""
+ span_group: SpanGroup = doc.spans["SPANS"]
+ spans: List[Span] = list(span_group)
+ for i, span in enumerate(span_group):
+ assert span == span_group[i] == spans[i]
+ filter_spans(span_group)
diff --git a/spacy/tests/doc/test_to_json.py b/spacy/tests/doc/test_to_json.py
deleted file mode 100644
index 9ebee6c88..000000000
--- a/spacy/tests/doc/test_to_json.py
+++ /dev/null
@@ -1,62 +0,0 @@
-import pytest
-from spacy.tokens import Doc
-
-
-@pytest.fixture()
-def doc(en_vocab):
- words = ["c", "d", "e"]
- pos = ["VERB", "NOUN", "NOUN"]
- tags = ["VBP", "NN", "NN"]
- heads = [0, 0, 0]
- deps = ["ROOT", "dobj", "dobj"]
- ents = ["O", "B-ORG", "O"]
- morphs = ["Feat1=A", "Feat1=B", "Feat1=A|Feat2=D"]
- return Doc(
- en_vocab,
- words=words,
- pos=pos,
- tags=tags,
- heads=heads,
- deps=deps,
- ents=ents,
- morphs=morphs,
- )
-
-
-def test_doc_to_json(doc):
- json_doc = doc.to_json()
- assert json_doc["text"] == "c d e "
- assert len(json_doc["tokens"]) == 3
- assert json_doc["tokens"][0]["pos"] == "VERB"
- assert json_doc["tokens"][0]["tag"] == "VBP"
- assert json_doc["tokens"][0]["dep"] == "ROOT"
- assert len(json_doc["ents"]) == 1
- assert json_doc["ents"][0]["start"] == 2 # character offset!
- assert json_doc["ents"][0]["end"] == 3 # character offset!
- assert json_doc["ents"][0]["label"] == "ORG"
-
-
-def test_doc_to_json_underscore(doc):
- Doc.set_extension("json_test1", default=False)
- Doc.set_extension("json_test2", default=False)
- doc._.json_test1 = "hello world"
- doc._.json_test2 = [1, 2, 3]
- json_doc = doc.to_json(underscore=["json_test1", "json_test2"])
- assert "_" in json_doc
- assert json_doc["_"]["json_test1"] == "hello world"
- assert json_doc["_"]["json_test2"] == [1, 2, 3]
-
-
-def test_doc_to_json_underscore_error_attr(doc):
- """Test that Doc.to_json() raises an error if a custom attribute doesn't
- exist in the ._ space."""
- with pytest.raises(ValueError):
- doc.to_json(underscore=["json_test3"])
-
-
-def test_doc_to_json_underscore_error_serialize(doc):
- """Test that Doc.to_json() raises an error if a custom attribute value
- isn't JSON-serializable."""
- Doc.set_extension("json_test4", method=lambda doc: doc.text)
- with pytest.raises(ValueError):
- doc.to_json(underscore=["json_test4"])
diff --git a/spacy/tests/lang/bg/test_tokenizer.py b/spacy/tests/lang/bg/test_tokenizer.py
new file mode 100644
index 000000000..2e2c45001
--- /dev/null
+++ b/spacy/tests/lang/bg/test_tokenizer.py
@@ -0,0 +1,8 @@
+import pytest
+
+
+def test_bg_tokenizer_handles_final_diacritics(bg_tokenizer):
+ text = "Ня̀маше яйца̀. Ня̀маше яйца̀."
+ tokens = bg_tokenizer(text)
+ assert tokens[1].text == "яйца̀"
+ assert tokens[2].text == "."
diff --git a/spacy/tests/lang/dsb/__init__.py b/spacy/tests/lang/dsb/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/spacy/tests/lang/dsb/test_text.py b/spacy/tests/lang/dsb/test_text.py
new file mode 100644
index 000000000..40f2c15e0
--- /dev/null
+++ b/spacy/tests/lang/dsb/test_text.py
@@ -0,0 +1,25 @@
+import pytest
+
+
+@pytest.mark.parametrize(
+ "text,match",
+ [
+ ("10", True),
+ ("1", True),
+ ("10,000", True),
+ ("10,00", True),
+ ("jadno", True),
+ ("dwanassćo", True),
+ ("milion", True),
+ ("sto", True),
+ ("ceła", False),
+ ("kopica", False),
+ ("narěcow", False),
+ (",", False),
+ ("1/2", True),
+ ],
+)
+def test_lex_attrs_like_number(dsb_tokenizer, text, match):
+ tokens = dsb_tokenizer(text)
+ assert len(tokens) == 1
+ assert tokens[0].like_num == match
diff --git a/spacy/tests/lang/dsb/test_tokenizer.py b/spacy/tests/lang/dsb/test_tokenizer.py
new file mode 100644
index 000000000..135974fb8
--- /dev/null
+++ b/spacy/tests/lang/dsb/test_tokenizer.py
@@ -0,0 +1,29 @@
+import pytest
+
+DSB_BASIC_TOKENIZATION_TESTS = [
+ (
+ "Ale eksistěrujo mimo togo ceła kopica narěcow, ako na pśikład slěpjańska.",
+ [
+ "Ale",
+ "eksistěrujo",
+ "mimo",
+ "togo",
+ "ceła",
+ "kopica",
+ "narěcow",
+ ",",
+ "ako",
+ "na",
+ "pśikład",
+ "slěpjańska",
+ ".",
+ ],
+ ),
+]
+
+
+@pytest.mark.parametrize("text,expected_tokens", DSB_BASIC_TOKENIZATION_TESTS)
+def test_dsb_tokenizer_basic(dsb_tokenizer, text, expected_tokens):
+ tokens = dsb_tokenizer(text)
+ token_list = [token.text for token in tokens if not token.is_space]
+ assert expected_tokens == token_list
diff --git a/spacy/tests/lang/en/test_tokenizer.py b/spacy/tests/lang/en/test_tokenizer.py
index e6d1d7d85..0133d00b0 100644
--- a/spacy/tests/lang/en/test_tokenizer.py
+++ b/spacy/tests/lang/en/test_tokenizer.py
@@ -167,3 +167,12 @@ def test_issue3521(en_tokenizer, word):
tok = en_tokenizer(word)[1]
# 'not' and 'would' should be stopwords, also in their abbreviated forms
assert tok.is_stop
+
+
+@pytest.mark.issue(10699)
+@pytest.mark.parametrize("text", ["theses", "thisre"])
+def test_issue10699(en_tokenizer, text):
+ """Test that 'theses' and 'thisre' are excluded from the contractions
+ generated by the English tokenizer exceptions."""
+ tokens = en_tokenizer(text)
+ assert len(tokens) == 1
diff --git a/spacy/tests/lang/grc/test_tokenizer.py b/spacy/tests/lang/grc/test_tokenizer.py
new file mode 100644
index 000000000..3df5b546b
--- /dev/null
+++ b/spacy/tests/lang/grc/test_tokenizer.py
@@ -0,0 +1,18 @@
+import pytest
+
+
+# fmt: off
+GRC_TOKEN_EXCEPTION_TESTS = [
+ ("τὸ 〈τῆς〉 φιλοσοφίας ἔργον ἔνιοί φασιν ἀπὸ ⟦βαρβάρων⟧ ἄρξαι.", ["τὸ", "〈", "τῆς", "〉", "φιλοσοφίας", "ἔργον", "ἔνιοί", "φασιν", "ἀπὸ", "⟦", "βαρβάρων", "⟧", "ἄρξαι", "."]),
+ ("τὴν δὲ τῶν Αἰγυπτίων φιλοσοφίαν εἶναι τοιαύτην περί τε †θεῶν† καὶ ὑπὲρ δικαιοσύνης.", ["τὴν", "δὲ", "τῶν", "Αἰγυπτίων", "φιλοσοφίαν", "εἶναι", "τοιαύτην", "περί", "τε", "†", "θεῶν", "†", "καὶ", "ὑπὲρ", "δικαιοσύνης", "."]),
+ ("⸏πόσις δ' Ἐρεχθεύς ἐστί μοι σεσωσμένος⸏", ["⸏", "πόσις", "δ'", "Ἐρεχθεύς", "ἐστί", "μοι", "σεσωσμένος", "⸏"]),
+ ("⸏ὔπνον ἴδωμεν⸎", ["⸏", "ὔπνον", "ἴδωμεν", "⸎"]),
+]
+# fmt: on
+
+
+@pytest.mark.parametrize("text,expected_tokens", GRC_TOKEN_EXCEPTION_TESTS)
+def test_grc_tokenizer(grc_tokenizer, text, expected_tokens):
+ tokens = grc_tokenizer(text)
+ token_list = [token.text for token in tokens if not token.is_space]
+ assert expected_tokens == token_list
diff --git a/spacy/tests/lang/hsb/__init__.py b/spacy/tests/lang/hsb/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/spacy/tests/lang/hsb/test_text.py b/spacy/tests/lang/hsb/test_text.py
new file mode 100644
index 000000000..aaa4984eb
--- /dev/null
+++ b/spacy/tests/lang/hsb/test_text.py
@@ -0,0 +1,25 @@
+import pytest
+
+
+@pytest.mark.parametrize(
+ "text,match",
+ [
+ ("10", True),
+ ("1", True),
+ ("10,000", True),
+ ("10,00", True),
+ ("jedne", True),
+ ("dwanaće", True),
+ ("milion", True),
+ ("sto", True),
+ ("załožene", False),
+ ("wona", False),
+ ("powšitkownej", False),
+ (",", False),
+ ("1/2", True),
+ ],
+)
+def test_lex_attrs_like_number(hsb_tokenizer, text, match):
+ tokens = hsb_tokenizer(text)
+ assert len(tokens) == 1
+ assert tokens[0].like_num == match
diff --git a/spacy/tests/lang/hsb/test_tokenizer.py b/spacy/tests/lang/hsb/test_tokenizer.py
new file mode 100644
index 000000000..a3ec89ba0
--- /dev/null
+++ b/spacy/tests/lang/hsb/test_tokenizer.py
@@ -0,0 +1,32 @@
+import pytest
+
+HSB_BASIC_TOKENIZATION_TESTS = [
+ (
+ "Hornjoserbšćina wobsteji resp. wobsteješe z wjacorych dialektow, kotrež so zdźěla chětro wot so rozeznawachu.",
+ [
+ "Hornjoserbšćina",
+ "wobsteji",
+ "resp.",
+ "wobsteješe",
+ "z",
+ "wjacorych",
+ "dialektow",
+ ",",
+ "kotrež",
+ "so",
+ "zdźěla",
+ "chětro",
+ "wot",
+ "so",
+ "rozeznawachu",
+ ".",
+ ],
+ ),
+]
+
+
+@pytest.mark.parametrize("text,expected_tokens", HSB_BASIC_TOKENIZATION_TESTS)
+def test_hsb_tokenizer_basic(hsb_tokenizer, text, expected_tokens):
+ tokens = hsb_tokenizer(text)
+ token_list = [token.text for token in tokens if not token.is_space]
+ assert expected_tokens == token_list
diff --git a/spacy/tests/lang/ko/test_tokenizer.py b/spacy/tests/lang/ko/test_tokenizer.py
index e6b65dee9..6e06e405e 100644
--- a/spacy/tests/lang/ko/test_tokenizer.py
+++ b/spacy/tests/lang/ko/test_tokenizer.py
@@ -49,6 +49,12 @@ def test_ko_empty_doc(ko_tokenizer):
assert len(tokens) == 0
+@pytest.mark.issue(10535)
+def test_ko_tokenizer_unknown_tag(ko_tokenizer):
+ tokens = ko_tokenizer("미닛 리피터")
+ assert tokens[1].pos_ == "X"
+
+
# fmt: off
SPACY_TOKENIZER_TESTS = [
("있다.", "있다 ."),
diff --git a/spacy/tests/lang/la/__init__.py b/spacy/tests/lang/la/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/spacy/tests/lang/la/test_exception.py b/spacy/tests/lang/la/test_exception.py
new file mode 100644
index 000000000..966ae22cf
--- /dev/null
+++ b/spacy/tests/lang/la/test_exception.py
@@ -0,0 +1,8 @@
+import pytest
+
+
+def test_la_tokenizer_handles_exc_in_text(la_tokenizer):
+ text = "scio te omnia facturum, ut nobiscum quam primum sis"
+ tokens = la_tokenizer(text)
+ assert len(tokens) == 11
+ assert tokens[6].text == "nobis"
diff --git a/spacy/tests/lang/la/test_text.py b/spacy/tests/lang/la/test_text.py
new file mode 100644
index 000000000..48e7359a4
--- /dev/null
+++ b/spacy/tests/lang/la/test_text.py
@@ -0,0 +1,35 @@
+import pytest
+from spacy.lang.la.lex_attrs import like_num
+
+
+@pytest.mark.parametrize(
+ "text,match",
+ [
+ ("IIII", True),
+ ("VI", True),
+ ("vi", True),
+ ("IV", True),
+ ("iv", True),
+ ("IX", True),
+ ("ix", True),
+ ("MMXXII", True),
+ ("0", True),
+ ("1", True),
+ ("quattuor", True),
+ ("decem", True),
+ ("tertius", True),
+ ("canis", False),
+ ("MMXX11", False),
+ (",", False),
+ ],
+)
+def test_lex_attrs_like_number(la_tokenizer, text, match):
+ tokens = la_tokenizer(text)
+ assert len(tokens) == 1
+ assert tokens[0].like_num == match
+
+
+@pytest.mark.parametrize("word", ["quinque"])
+def test_la_lex_attrs_capitals(word):
+ assert like_num(word)
+ assert like_num(word.upper())
diff --git a/spacy/tests/lang/lg/__init__.py b/spacy/tests/lang/lg/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/spacy/tests/lang/lg/test_tokenizer.py b/spacy/tests/lang/lg/test_tokenizer.py
new file mode 100644
index 000000000..958385a77
--- /dev/null
+++ b/spacy/tests/lang/lg/test_tokenizer.py
@@ -0,0 +1,15 @@
+import pytest
+
+LG_BASIC_TOKENIZATION_TESTS = [
+ (
+ "Abooluganda ab’emmamba ababiri",
+ ["Abooluganda", "ab’emmamba", "ababiri"],
+ ),
+]
+
+
+@pytest.mark.parametrize("text,expected_tokens", LG_BASIC_TOKENIZATION_TESTS)
+def test_lg_tokenizer_basic(lg_tokenizer, text, expected_tokens):
+ tokens = lg_tokenizer(text)
+ token_list = [token.text for token in tokens if not token.is_space]
+ assert expected_tokens == token_list
diff --git a/spacy/tests/lang/nl/test_noun_chunks.py b/spacy/tests/lang/nl/test_noun_chunks.py
index 73b501e4a..8962e3b75 100644
--- a/spacy/tests/lang/nl/test_noun_chunks.py
+++ b/spacy/tests/lang/nl/test_noun_chunks.py
@@ -1,5 +1,6 @@
-from spacy.tokens import Doc
import pytest
+from spacy.tokens import Doc
+from spacy.util import filter_spans
@pytest.fixture
@@ -207,3 +208,18 @@ def test_chunking(nl_sample, nl_reference_chunking):
"""
chunks = [s.text.lower() for s in nl_sample.noun_chunks]
assert chunks == nl_reference_chunking
+
+
+@pytest.mark.issue(10846)
+def test_no_overlapping_chunks(nl_vocab):
+ # fmt: off
+ doc = Doc(
+ nl_vocab,
+ words=["Dit", "programma", "wordt", "beschouwd", "als", "'s", "werelds", "eerste", "computerprogramma"],
+ deps=["det", "nsubj:pass", "aux:pass", "ROOT", "mark", "det", "fixed", "amod", "xcomp"],
+ heads=[1, 3, 3, 3, 8, 8, 5, 8, 3],
+ pos=["DET", "NOUN", "AUX", "VERB", "SCONJ", "DET", "NOUN", "ADJ", "NOUN"],
+ )
+ # fmt: on
+ chunks = list(doc.noun_chunks)
+ assert filter_spans(chunks) == chunks
diff --git a/spacy/tests/lang/ru/test_lemmatizer.py b/spacy/tests/lang/ru/test_lemmatizer.py
index 3810323bf..9a5a9ad68 100644
--- a/spacy/tests/lang/ru/test_lemmatizer.py
+++ b/spacy/tests/lang/ru/test_lemmatizer.py
@@ -2,6 +2,9 @@ import pytest
from spacy.tokens import Doc
+pytestmark = pytest.mark.filterwarnings("ignore::DeprecationWarning")
+
+
def test_ru_doc_lemmatization(ru_lemmatizer):
words = ["мама", "мыла", "раму"]
pos = ["NOUN", "VERB", "NOUN"]
@@ -75,3 +78,32 @@ def test_ru_lemmatizer_punct(ru_lemmatizer):
assert ru_lemmatizer.pymorphy2_lemmatize(doc[0]) == ['"']
doc = Doc(ru_lemmatizer.vocab, words=["»"], pos=["PUNCT"])
assert ru_lemmatizer.pymorphy2_lemmatize(doc[0]) == ['"']
+
+
+def test_ru_doc_lookup_lemmatization(ru_lookup_lemmatizer):
+ assert ru_lookup_lemmatizer.mode == "pymorphy3_lookup"
+ words = ["мама", "мыла", "раму"]
+ pos = ["NOUN", "VERB", "NOUN"]
+ morphs = [
+ "Animacy=Anim|Case=Nom|Gender=Fem|Number=Sing",
+ "Aspect=Imp|Gender=Fem|Mood=Ind|Number=Sing|Tense=Past|VerbForm=Fin|Voice=Act",
+ "Animacy=Anim|Case=Acc|Gender=Fem|Number=Sing",
+ ]
+ doc = Doc(ru_lookup_lemmatizer.vocab, words=words, pos=pos, morphs=morphs)
+ doc = ru_lookup_lemmatizer(doc)
+ lemmas = [token.lemma_ for token in doc]
+ assert lemmas == ["мама", "мыла", "раму"]
+
+
+@pytest.mark.parametrize(
+ "word,lemma",
+ (
+ ("бременем", "бремя"),
+ ("будешь", "быть"),
+ ("какая-то", "какой-то"),
+ ),
+)
+def test_ru_lookup_lemmatizer(ru_lookup_lemmatizer, word, lemma):
+ assert ru_lookup_lemmatizer.mode == "pymorphy3_lookup"
+ doc = Doc(ru_lookup_lemmatizer.vocab, words=[word])
+ assert ru_lookup_lemmatizer(doc)[0].lemma_ == lemma
diff --git a/spacy/tests/lang/ru/test_tokenizer.py b/spacy/tests/lang/ru/test_tokenizer.py
index 1cfdc50ee..083b55a09 100644
--- a/spacy/tests/lang/ru/test_tokenizer.py
+++ b/spacy/tests/lang/ru/test_tokenizer.py
@@ -1,3 +1,4 @@
+from string import punctuation
import pytest
@@ -122,3 +123,36 @@ def test_ru_tokenizer_splits_bracket_period(ru_tokenizer):
text = "(Раз, два, три, проверка)."
tokens = ru_tokenizer(text)
assert tokens[len(tokens) - 1].text == "."
+
+
+@pytest.mark.parametrize(
+ "text",
+ [
+ "рекоменду́я подда́ть жару́. Самого́ Баргамота",
+ "РЕКОМЕНДУ́Я ПОДДА́ТЬ ЖАРУ́. САМОГО́ БАРГАМОТА",
+ "рекоменду̍я подда̍ть жару̍.Самого̍ Баргамота",
+ "рекоменду̍я подда̍ть жару̍.'Самого̍ Баргамота",
+ "рекоменду̍я подда̍ть жару̍,самого̍ Баргамота",
+ "рекоменду̍я подда̍ть жару̍:самого̍ Баргамота",
+ "рекоменду̍я подда̍ть жару̍. самого̍ Баргамота",
+ "рекоменду̍я подда̍ть жару̍, самого̍ Баргамота",
+ "рекоменду̍я подда̍ть жару̍: самого̍ Баргамота",
+ "рекоменду̍я подда̍ть жару̍-самого̍ Баргамота",
+ ],
+)
+def test_ru_tokenizer_handles_final_diacritics(ru_tokenizer, text):
+ tokens = ru_tokenizer(text)
+ assert tokens[2].text in ("жару́", "ЖАРУ́", "жару̍")
+ assert tokens[3].text in punctuation
+
+
+@pytest.mark.parametrize(
+ "text",
+ [
+ "РЕКОМЕНДУ́Я ПОДДА́ТЬ ЖАРУ́.САМОГО́ БАРГАМОТА",
+ "рекоменду̍я подда̍ть жару́.самого́ Баргамота",
+ ],
+)
+def test_ru_tokenizer_handles_final_diacritic_and_period(ru_tokenizer, text):
+ tokens = ru_tokenizer(text)
+ assert tokens[2].text.lower() == "жару́.самого́"
diff --git a/spacy/tests/lang/sl/test_text.py b/spacy/tests/lang/sl/test_text.py
index ddc5b6b5d..a2a932077 100644
--- a/spacy/tests/lang/sl/test_text.py
+++ b/spacy/tests/lang/sl/test_text.py
@@ -20,7 +20,6 @@ od katerih so te svoboščine odvisne,
assert len(tokens) == 116
-@pytest.mark.xfail
def test_ordinal_number(sl_tokenizer):
text = "10. decembra 1948"
tokens = sl_tokenizer(text)
diff --git a/spacy/tests/lang/ta/__init__.py b/spacy/tests/lang/ta/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/spacy/tests/lang/ta/test_text.py b/spacy/tests/lang/ta/test_text.py
new file mode 100644
index 000000000..228a14c18
--- /dev/null
+++ b/spacy/tests/lang/ta/test_text.py
@@ -0,0 +1,25 @@
+import pytest
+from spacy.lang.ta import Tamil
+
+# Wikipedia excerpt: https://en.wikipedia.org/wiki/Chennai (Tamil Language)
+TAMIL_BASIC_TOKENIZER_SENTENCIZER_TEST_TEXT = """சென்னை (Chennai) தமிழ்நாட்டின் தலைநகரமும், இந்தியாவின் நான்காவது பெரிய நகரமும் ஆகும். 1996 ஆம் ஆண்டுக்கு முன்னர் இந்நகரம், மதராசு பட்டினம், மெட்ராஸ் (Madras) மற்றும் சென்னப்பட்டினம் என்றும் அழைக்கப்பட்டு வந்தது. சென்னை, வங்காள விரிகுடாவின் கரையில் அமைந்த துறைமுக நகரங்களுள் ஒன்று. சுமார் 10 மில்லியன் (ஒரு கோடி) மக்கள் வாழும் இந்நகரம், உலகின் 35 பெரிய மாநகரங்களுள் ஒன்று. 17ஆம் நூற்றாண்டில் ஆங்கிலேயர் சென்னையில் கால் பதித்தது முதல், சென்னை நகரம் ஒரு முக்கிய நகரமாக வளர்ந்து வந்திருக்கிறது. சென்னை தென்னிந்தியாவின் வாசலாகக் கருதப்படுகிறது. சென்னை நகரில் உள்ள மெரினா கடற்கரை உலகின் நீளமான கடற்கரைகளுள் ஒன்று. சென்னை கோலிவுட் (Kollywood) என அறியப்படும் தமிழ்த் திரைப்படத் துறையின் தாயகம் ஆகும். பல விளையாட்டு அரங்கங்கள் உள்ள சென்னையில் பல விளையாட்டுப் போட்டிகளும் நடைபெறுகின்றன."""
+
+
+@pytest.mark.parametrize(
+ "text, num_tokens",
+ [(TAMIL_BASIC_TOKENIZER_SENTENCIZER_TEST_TEXT, 23 + 90)], # Punctuation + rest
+)
+def test_long_text(ta_tokenizer, text, num_tokens):
+ tokens = ta_tokenizer(text)
+ assert len(tokens) == num_tokens
+
+
+@pytest.mark.parametrize(
+ "text, num_sents", [(TAMIL_BASIC_TOKENIZER_SENTENCIZER_TEST_TEXT, 9)]
+)
+def test_ta_sentencizer(text, num_sents):
+ nlp = Tamil()
+ nlp.add_pipe("sentencizer")
+
+ doc = nlp(text)
+ assert len(list(doc.sents)) == num_sents
diff --git a/spacy/tests/lang/ta/test_tokenizer.py b/spacy/tests/lang/ta/test_tokenizer.py
new file mode 100644
index 000000000..6ba8a2400
--- /dev/null
+++ b/spacy/tests/lang/ta/test_tokenizer.py
@@ -0,0 +1,188 @@
+import pytest
+from spacy.symbols import ORTH
+from spacy.lang.ta import Tamil
+
+TA_BASIC_TOKENIZATION_TESTS = [
+ (
+ "கிறிஸ்துமஸ் மற்றும் இனிய புத்தாண்டு வாழ்த்துக்கள்",
+ ["கிறிஸ்துமஸ்", "மற்றும்", "இனிய", "புத்தாண்டு", "வாழ்த்துக்கள்"],
+ ),
+ (
+ "எனக்கு என் குழந்தைப் பருவம் நினைவிருக்கிறது",
+ ["எனக்கு", "என்", "குழந்தைப்", "பருவம்", "நினைவிருக்கிறது"],
+ ),
+ ("உங்கள் பெயர் என்ன?", ["உங்கள்", "பெயர்", "என்ன", "?"]),
+ (
+ "ஏறத்தாழ இலங்கைத் தமிழரில் மூன்றிலொரு பங்கினர் இலங்கையை விட்டு வெளியேறிப் பிற நாடுகளில் வாழ்கின்றனர்",
+ [
+ "ஏறத்தாழ",
+ "இலங்கைத்",
+ "தமிழரில்",
+ "மூன்றிலொரு",
+ "பங்கினர்",
+ "இலங்கையை",
+ "விட்டு",
+ "வெளியேறிப்",
+ "பிற",
+ "நாடுகளில்",
+ "வாழ்கின்றனர்",
+ ],
+ ),
+ (
+ "இந்த ஃபோனுடன் சுமார் ரூ.2,990 மதிப்புள்ள போட் ராக்கர்ஸ் நிறுவனத்தின் ஸ்போர்ட் புளூடூத் ஹெட்போன்ஸ் இலவசமாக வழங்கப்படவுள்ளது.",
+ [
+ "இந்த",
+ "ஃபோனுடன்",
+ "சுமார்",
+ "ரூ.2,990",
+ "மதிப்புள்ள",
+ "போட்",
+ "ராக்கர்ஸ்",
+ "நிறுவனத்தின்",
+ "ஸ்போர்ட்",
+ "புளூடூத்",
+ "ஹெட்போன்ஸ்",
+ "இலவசமாக",
+ "வழங்கப்படவுள்ளது",
+ ".",
+ ],
+ ),
+ (
+ "மட்டக்களப்பில் பல இடங்களில் வீட்டுத் திட்டங்களுக்கு இன்று அடிக்கல் நாட்டல்",
+ [
+ "மட்டக்களப்பில்",
+ "பல",
+ "இடங்களில்",
+ "வீட்டுத்",
+ "திட்டங்களுக்கு",
+ "இன்று",
+ "அடிக்கல்",
+ "நாட்டல்",
+ ],
+ ),
+ (
+ "ஐ போன்க்கு முகத்தை வைத்து அன்லாக் செய்யும் முறை மற்றும் விரலால் தொட்டு அன்லாக் செய்யும் முறையை வாட்ஸ் ஆப் நிறுவனம் இதற்கு முன் கண்டுபிடித்தது",
+ [
+ "ஐ",
+ "போன்க்கு",
+ "முகத்தை",
+ "வைத்து",
+ "அன்லாக்",
+ "செய்யும்",
+ "முறை",
+ "மற்றும்",
+ "விரலால்",
+ "தொட்டு",
+ "அன்லாக்",
+ "செய்யும்",
+ "முறையை",
+ "வாட்ஸ்",
+ "ஆப்",
+ "நிறுவனம்",
+ "இதற்கு",
+ "முன்",
+ "கண்டுபிடித்தது",
+ ],
+ ),
+ (
+ "இது ஒரு வாக்கியம்.",
+ [
+ "இது",
+ "ஒரு",
+ "வாக்கியம்",
+ ".",
+ ],
+ ),
+ (
+ "தன்னாட்சி கார்கள் காப்பீட்டு பொறுப்பை உற்பத்தியாளரிடம் மாற்றுகின்றன",
+ [
+ "தன்னாட்சி",
+ "கார்கள்",
+ "காப்பீட்டு",
+ "பொறுப்பை",
+ "உற்பத்தியாளரிடம்",
+ "மாற்றுகின்றன",
+ ],
+ ),
+ (
+ "நடைபாதை விநியோக ரோபோக்களை தடை செய்வதை சான் பிரான்சிஸ்கோ கருதுகிறது",
+ [
+ "நடைபாதை",
+ "விநியோக",
+ "ரோபோக்களை",
+ "தடை",
+ "செய்வதை",
+ "சான்",
+ "பிரான்சிஸ்கோ",
+ "கருதுகிறது",
+ ],
+ ),
+ (
+ "லண்டன் ஐக்கிய இராச்சியத்தில் ஒரு பெரிய நகரம்.",
+ [
+ "லண்டன்",
+ "ஐக்கிய",
+ "இராச்சியத்தில்",
+ "ஒரு",
+ "பெரிய",
+ "நகரம்",
+ ".",
+ ],
+ ),
+ (
+ "என்ன வேலை செய்கிறீர்கள்?",
+ [
+ "என்ன",
+ "வேலை",
+ "செய்கிறீர்கள்",
+ "?",
+ ],
+ ),
+ (
+ "எந்த கல்லூரியில் படிக்கிறாய்?",
+ [
+ "எந்த",
+ "கல்லூரியில்",
+ "படிக்கிறாய்",
+ "?",
+ ],
+ ),
+]
+
+
+@pytest.mark.parametrize("text,expected_tokens", TA_BASIC_TOKENIZATION_TESTS)
+def test_ta_tokenizer_basic(ta_tokenizer, text, expected_tokens):
+ tokens = ta_tokenizer(text)
+ token_list = [token.text for token in tokens]
+ assert expected_tokens == token_list
+
+
+@pytest.mark.parametrize(
+ "text,expected_tokens",
+ [
+ (
+ "ஆப்பிள் நிறுவனம் யு.கே. தொடக்க நிறுவனத்தை ஒரு லட்சம் கோடிக்கு வாங்கப் பார்க்கிறது",
+ [
+ "ஆப்பிள்",
+ "நிறுவனம்",
+ "யு.கே.",
+ "தொடக்க",
+ "நிறுவனத்தை",
+ "ஒரு",
+ "லட்சம்",
+ "கோடிக்கு",
+ "வாங்கப்",
+ "பார்க்கிறது",
+ ],
+ )
+ ],
+)
+def test_ta_tokenizer_special_case(text, expected_tokens):
+ # Add a special rule to tokenize the initialism "யு.கே." (U.K., as
+ # in the country) as a single token.
+ nlp = Tamil()
+ nlp.tokenizer.add_special_case("யு.கே.", [{ORTH: "யு.கே."}])
+ tokens = nlp(text)
+
+ token_list = [token.text for token in tokens]
+ assert expected_tokens == token_list
diff --git a/spacy/tests/lang/tr/test_text.py b/spacy/tests/lang/tr/test_text.py
index a12971e82..323b11bd1 100644
--- a/spacy/tests/lang/tr/test_text.py
+++ b/spacy/tests/lang/tr/test_text.py
@@ -41,7 +41,7 @@ def test_tr_lex_attrs_like_number_cardinal_ordinal(word):
assert like_num(word)
-@pytest.mark.parametrize("word", ["beş", "yedi", "yedinci", "birinci"])
+@pytest.mark.parametrize("word", ["beş", "yedi", "yedinci", "birinci", "milyonuncu"])
def test_tr_lex_attrs_capitals(word):
assert like_num(word)
assert like_num(word.upper())
diff --git a/spacy/tests/lang/tr/test_tokenizer.py b/spacy/tests/lang/tr/test_tokenizer.py
index 2ceca5068..9f988eae9 100644
--- a/spacy/tests/lang/tr/test_tokenizer.py
+++ b/spacy/tests/lang/tr/test_tokenizer.py
@@ -694,5 +694,4 @@ TESTS = ABBREV_TESTS + URL_TESTS + NUMBER_TESTS + PUNCT_TESTS + GENERAL_TESTS
def test_tr_tokenizer_handles_allcases(tr_tokenizer, text, expected_tokens):
tokens = tr_tokenizer(text)
token_list = [token.text for token in tokens if not token.is_space]
- print(token_list)
assert expected_tokens == token_list
diff --git a/spacy/tests/lang/uk/test_lemmatizer.py b/spacy/tests/lang/uk/test_lemmatizer.py
index 4a787b2a6..a65bb25e5 100644
--- a/spacy/tests/lang/uk/test_lemmatizer.py
+++ b/spacy/tests/lang/uk/test_lemmatizer.py
@@ -1,7 +1,27 @@
+import pytest
from spacy.tokens import Doc
+pytestmark = pytest.mark.filterwarnings("ignore::DeprecationWarning")
+
+
def test_uk_lemmatizer(uk_lemmatizer):
"""Check that the default uk lemmatizer runs."""
doc = Doc(uk_lemmatizer.vocab, words=["a", "b", "c"])
+ assert uk_lemmatizer.mode == "pymorphy3"
uk_lemmatizer(doc)
+ assert [token.lemma for token in doc]
+
+
+@pytest.mark.parametrize(
+ "word,lemma",
+ (
+ ("якийсь", "якийсь"),
+ ("розповідають", "розповідати"),
+ ("розповіси", "розповісти"),
+ ),
+)
+def test_uk_lookup_lemmatizer(uk_lookup_lemmatizer, word, lemma):
+ assert uk_lookup_lemmatizer.mode == "pymorphy3_lookup"
+ doc = Doc(uk_lookup_lemmatizer.vocab, words=[word])
+ assert uk_lookup_lemmatizer(doc)[0].lemma_ == lemma
diff --git a/spacy/tests/lang/uk/test_tokenizer.py b/spacy/tests/lang/uk/test_tokenizer.py
index 3d6e87301..6596f490a 100644
--- a/spacy/tests/lang/uk/test_tokenizer.py
+++ b/spacy/tests/lang/uk/test_tokenizer.py
@@ -140,3 +140,10 @@ def test_uk_tokenizer_splits_bracket_period(uk_tokenizer):
text = "(Раз, два, три, проверка)."
tokens = uk_tokenizer(text)
assert tokens[len(tokens) - 1].text == "."
+
+
+def test_uk_tokenizer_handles_final_diacritics(uk_tokenizer):
+ text = "Хлібі́в не було́. Хлібі́в не було́."
+ tokens = uk_tokenizer(text)
+ assert tokens[2].text == "було́"
+ assert tokens[3].text == "."
diff --git a/spacy/tests/matcher/test_dependency_matcher.py b/spacy/tests/matcher/test_dependency_matcher.py
index 1728c82af..b4e19d69d 100644
--- a/spacy/tests/matcher/test_dependency_matcher.py
+++ b/spacy/tests/matcher/test_dependency_matcher.py
@@ -316,6 +316,20 @@ def test_dependency_matcher_precedence_ops(en_vocab, op, num_matches):
("the", "brown", "$--", 0),
("brown", "the", "$--", 1),
("brown", "brown", "$--", 0),
+ ("quick", "fox", "<++", 1),
+ ("quick", "over", "<++", 0),
+ ("over", "jumped", "<++", 0),
+ ("the", "fox", "<++", 2),
+ ("brown", "fox", "<--", 0),
+ ("fox", "jumped", "<--", 0),
+ ("fox", "over", "<--", 1),
+ ("jumped", "over", ">++", 1),
+ ("fox", "lazy", ">++", 0),
+ ("over", "the", ">++", 0),
+ ("brown", "fox", ">--", 0),
+ ("fox", "brown", ">--", 1),
+ ("jumped", "fox", ">--", 1),
+ ("fox", "the", ">--", 2),
],
)
def test_dependency_matcher_ops(en_vocab, doc, left, right, op, num_matches):
diff --git a/spacy/tests/matcher/test_levenshtein.py b/spacy/tests/matcher/test_levenshtein.py
new file mode 100644
index 000000000..5afb7e1fc
--- /dev/null
+++ b/spacy/tests/matcher/test_levenshtein.py
@@ -0,0 +1,73 @@
+import pytest
+from spacy.matcher import levenshtein
+from spacy.matcher.levenshtein import levenshtein_compare
+
+
+# empty string plus 10 random ASCII, 10 random unicode, and 2 random long tests
+# from polyleven
+@pytest.mark.parametrize(
+ "dist,a,b",
+ [
+ (0, "", ""),
+ (4, "bbcb", "caba"),
+ (3, "abcb", "cacc"),
+ (3, "aa", "ccc"),
+ (1, "cca", "ccac"),
+ (1, "aba", "aa"),
+ (4, "bcbb", "abac"),
+ (3, "acbc", "bba"),
+ (3, "cbba", "a"),
+ (2, "bcc", "ba"),
+ (4, "aaa", "ccbb"),
+ (3, "うあい", "いいうい"),
+ (2, "あううい", "うあい"),
+ (3, "いういい", "うううあ"),
+ (2, "うい", "あいあ"),
+ (2, "いあい", "いう"),
+ (1, "いい", "あいい"),
+ (3, "あうあ", "いいああ"),
+ (4, "いあうう", "ううああ"),
+ (3, "いあいい", "ういああ"),
+ (3, "いいああ", "ううあう"),
+ (
+ 166,
+ "TCTGGGCACGGATTCGTCAGATTCCATGTCCATATTTGAGGCTCTTGCAGGCAAAATTTGGGCATGTGAACTCCTTATAGTCCCCGTGC",
+ "ATATGGATTGGGGGCATTCAAAGATACGGTTTCCCTTTCTTCAGTTTCGCGCGGCGCACGTCCGGGTGCGAGCCAGTTCGTCTTACTCACATTGTCGACTTCACGAATCGCGCATGATGTGCTTAGCCTGTACTTACGAACGAACTTTCGGTCCAAATACATTCTATCAACACCGAGGTATCCGTGCCACACGCCGAAGCTCGACCGTGTTCGTTGAGAGGTGGAAATGGTAAAAGATGAACATAGTC",
+ ),
+ (
+ 111,
+ "GGTTCGGCCGAATTCATAGAGCGTGGTAGTCGACGGTATCCCGCCTGGTAGGGGCCCCTTCTACCTAGCGGAAGTTTGTCAGTACTCTATAACACGAGGGCCTCTCACACCCTAGATCGTCCAGCCACTCGAAGATCGCAGCACCCTTACAGAAAGGCATTAATGTTTCTCCTAGCACTTGTGCAATGGTGAAGGAGTGATG",
+ "CGTAACACTTCGCGCTACTGGGCTGCAACGTCTTGGGCATACATGCAAGATTATCTAATGCAAGCTTGAGCCCCGCTTGCGGAATTTCCCTAATCGGGGTCCCTTCCTGTTACGATAAGGACGCGTGCACT",
+ ),
+ ],
+)
+def test_levenshtein(dist, a, b):
+ assert levenshtein(a, b) == dist
+
+
+@pytest.mark.parametrize(
+ "a,b,fuzzy,expected",
+ [
+ ("a", "a", 1, True),
+ ("a", "a", 0, True),
+ ("a", "a", -1, True),
+ ("a", "ab", 1, True),
+ ("a", "ab", 0, False),
+ ("a", "ab", -1, True),
+ ("ab", "ac", 1, True),
+ ("ab", "ac", -1, True),
+ ("abc", "cde", 4, True),
+ ("abc", "cde", -1, False),
+ ("abcdef", "cdefgh", 4, True),
+ ("abcdef", "cdefgh", 3, False),
+ ("abcdef", "cdefgh", -1, False), # default (2 for length 6)
+ ("abcdefgh", "cdefghijk", 5, True),
+ ("abcdefgh", "cdefghijk", 4, False),
+ ("abcdefgh", "cdefghijk", -1, False), # default (2)
+ ("abcdefgh", "cdefghijkl", 6, True),
+ ("abcdefgh", "cdefghijkl", 5, False),
+ ("abcdefgh", "cdefghijkl", -1, False), # default (2)
+ ],
+)
+def test_levenshtein_compare(a, b, fuzzy, expected):
+ assert levenshtein_compare(a, b, fuzzy) == expected
diff --git a/spacy/tests/matcher/test_matcher_api.py b/spacy/tests/matcher/test_matcher_api.py
index a27baf130..09ab6c7dc 100644
--- a/spacy/tests/matcher/test_matcher_api.py
+++ b/spacy/tests/matcher/test_matcher_api.py
@@ -118,6 +118,155 @@ def test_matcher_match_multi(matcher):
]
+@pytest.mark.parametrize(
+ "rules,match_locs",
+ [
+ (
+ {
+ "GoogleNow": [[{"ORTH": {"FUZZY": "Google"}}, {"ORTH": "Now"}]],
+ },
+ [(2, 4)],
+ ),
+ (
+ {
+ "Java": [[{"LOWER": {"FUZZY": "java"}}]],
+ },
+ [(5, 6)],
+ ),
+ (
+ {
+ "JS": [[{"ORTH": {"FUZZY": "JavaScript"}}]],
+ "GoogleNow": [[{"ORTH": {"FUZZY": "Google"}}, {"ORTH": "Now"}]],
+ "Java": [[{"LOWER": {"FUZZY": "java"}}]],
+ },
+ [(2, 4), (5, 6), (8, 9)],
+ ),
+ # only the second pattern matches (check that predicate keys used for
+ # caching don't collide)
+ (
+ {
+ "A": [[{"ORTH": {"FUZZY": "Javascripts"}}]],
+ "B": [[{"ORTH": {"FUZZY5": "Javascripts"}}]],
+ },
+ [(8, 9)],
+ ),
+ ],
+)
+def test_matcher_match_fuzzy(en_vocab, rules, match_locs):
+ words = ["They", "like", "Goggle", "Now", "and", "Jav", "but", "not", "JvvaScrpt"]
+ doc = Doc(en_vocab, words=words)
+
+ matcher = Matcher(en_vocab)
+ for key, patterns in rules.items():
+ matcher.add(key, patterns)
+ assert match_locs == [(start, end) for m_id, start, end in matcher(doc)]
+
+
+@pytest.mark.parametrize("set_op", ["IN", "NOT_IN"])
+def test_matcher_match_fuzzy_set_op_longest(en_vocab, set_op):
+ rules = {
+ "GoogleNow": [[{"ORTH": {"FUZZY": {set_op: ["Google", "Now"]}}, "OP": "+"}]]
+ }
+ matcher = Matcher(en_vocab)
+ for key, patterns in rules.items():
+ matcher.add(key, patterns, greedy="LONGEST")
+
+ words = ["They", "like", "Goggle", "Noo"]
+ doc = Doc(en_vocab, words=words)
+ assert len(matcher(doc)) == 1
+
+
+def test_matcher_match_fuzzy_set_multiple(en_vocab):
+ rules = {
+ "GoogleNow": [
+ [
+ {
+ "ORTH": {"FUZZY": {"IN": ["Google", "Now"]}, "NOT_IN": ["Goggle"]},
+ "OP": "+",
+ }
+ ]
+ ]
+ }
+ matcher = Matcher(en_vocab)
+ for key, patterns in rules.items():
+ matcher.add(key, patterns, greedy="LONGEST")
+
+ words = ["They", "like", "Goggle", "Noo"]
+ doc = Doc(matcher.vocab, words=words)
+ assert matcher(doc) == [
+ (doc.vocab.strings["GoogleNow"], 3, 4),
+ ]
+
+
+@pytest.mark.parametrize("fuzzyn", range(1, 10))
+def test_matcher_match_fuzzyn_all_insertions(en_vocab, fuzzyn):
+ matcher = Matcher(en_vocab)
+ matcher.add("GoogleNow", [[{"ORTH": {f"FUZZY{fuzzyn}": "GoogleNow"}}]])
+ # words with increasing edit distance
+ words = ["GoogleNow" + "a" * i for i in range(0, 10)]
+ doc = Doc(en_vocab, words)
+ assert len(matcher(doc)) == fuzzyn + 1
+
+
+@pytest.mark.parametrize("fuzzyn", range(1, 6))
+def test_matcher_match_fuzzyn_various_edits(en_vocab, fuzzyn):
+ matcher = Matcher(en_vocab)
+ matcher.add("GoogleNow", [[{"ORTH": {f"FUZZY{fuzzyn}": "GoogleNow"}}]])
+ # words with increasing edit distance of different edit types
+ words = [
+ "GoogleNow",
+ "GoogleNuw",
+ "GoogleNuew",
+ "GoogleNoweee",
+ "GiggleNuw3",
+ "gouggle5New",
+ ]
+ doc = Doc(en_vocab, words)
+ assert len(matcher(doc)) == fuzzyn + 1
+
+
+@pytest.mark.parametrize("greedy", ["FIRST", "LONGEST"])
+@pytest.mark.parametrize("set_op", ["IN", "NOT_IN"])
+def test_matcher_match_fuzzyn_set_op_longest(en_vocab, greedy, set_op):
+ rules = {
+ "GoogleNow": [[{"ORTH": {"FUZZY2": {set_op: ["Google", "Now"]}}, "OP": "+"}]]
+ }
+ matcher = Matcher(en_vocab)
+ for key, patterns in rules.items():
+ matcher.add(key, patterns, greedy=greedy)
+
+ words = ["They", "like", "Goggle", "Noo"]
+ doc = Doc(matcher.vocab, words=words)
+ spans = matcher(doc, as_spans=True)
+ assert len(spans) == 1
+ if set_op == "IN":
+ assert spans[0].text == "Goggle Noo"
+ else:
+ assert spans[0].text == "They like"
+
+
+def test_matcher_match_fuzzyn_set_multiple(en_vocab):
+ rules = {
+ "GoogleNow": [
+ [
+ {
+ "ORTH": {"FUZZY1": {"IN": ["Google", "Now"]}, "NOT_IN": ["Goggle"]},
+ "OP": "+",
+ }
+ ]
+ ]
+ }
+ matcher = Matcher(en_vocab)
+ for key, patterns in rules.items():
+ matcher.add(key, patterns, greedy="LONGEST")
+
+ words = ["They", "like", "Goggle", "Noo"]
+ doc = Doc(matcher.vocab, words=words)
+ assert matcher(doc) == [
+ (doc.vocab.strings["GoogleNow"], 3, 4),
+ ]
+
+
def test_matcher_empty_dict(en_vocab):
"""Test matcher allows empty token specs, meaning match on any token."""
matcher = Matcher(en_vocab)
@@ -368,6 +517,16 @@ def test_matcher_intersect_value_operator(en_vocab):
doc[0]._.ext = ["A", "B"]
assert len(matcher(doc)) == 1
+ # INTERSECTS matches nothing for iterables that aren't all str or int
+ matcher = Matcher(en_vocab)
+ pattern = [{"_": {"ext": {"INTERSECTS": ["Abx", "C"]}}}]
+ matcher.add("M", [pattern])
+ doc = Doc(en_vocab, words=["a", "b", "c"])
+ doc[0]._.ext = [["Abx"], "B"]
+ assert len(matcher(doc)) == 0
+ doc[0]._.ext = ["Abx", "B"]
+ assert len(matcher(doc)) == 1
+
# INTERSECTS with an empty pattern list matches nothing
matcher = Matcher(en_vocab)
pattern = [{"_": {"ext": {"INTERSECTS": []}}}]
@@ -427,6 +586,30 @@ def test_matcher_regex(en_vocab):
assert len(matches) == 0
+def test_matcher_regex_set_in(en_vocab):
+ matcher = Matcher(en_vocab)
+ pattern = [{"ORTH": {"REGEX": {"IN": [r"(?:a)", r"(?:an)"]}}}]
+ matcher.add("A_OR_AN", [pattern])
+ doc = Doc(en_vocab, words=["an", "a", "hi"])
+ matches = matcher(doc)
+ assert len(matches) == 2
+ doc = Doc(en_vocab, words=["bye"])
+ matches = matcher(doc)
+ assert len(matches) == 0
+
+
+def test_matcher_regex_set_not_in(en_vocab):
+ matcher = Matcher(en_vocab)
+ pattern = [{"ORTH": {"REGEX": {"NOT_IN": [r"(?:a)", r"(?:an)"]}}}]
+ matcher.add("A_OR_AN", [pattern])
+ doc = Doc(en_vocab, words=["an", "a", "hi"])
+ matches = matcher(doc)
+ assert len(matches) == 1
+ doc = Doc(en_vocab, words=["bye"])
+ matches = matcher(doc)
+ assert len(matches) == 1
+
+
def test_matcher_regex_shape(en_vocab):
matcher = Matcher(en_vocab)
pattern = [{"SHAPE": {"REGEX": r"^[^x]+$"}}]
@@ -476,6 +659,25 @@ def test_matcher_extension_set_membership(en_vocab):
assert len(matches) == 0
+def test_matcher_extension_in_set_predicate(en_vocab):
+ matcher = Matcher(en_vocab)
+ Token.set_extension("ext", default=[])
+ pattern = [{"_": {"ext": {"IN": ["A", "C"]}}}]
+ matcher.add("M", [pattern])
+ doc = Doc(en_vocab, words=["a", "b", "c"])
+
+ # The IN predicate expects an exact match between the
+ # extension value and one of the pattern's values.
+ doc[0]._.ext = ["A", "B"]
+ assert len(matcher(doc)) == 0
+
+ doc[0]._.ext = ["A"]
+ assert len(matcher(doc)) == 0
+
+ doc[0]._.ext = "A"
+ assert len(matcher(doc)) == 1
+
+
def test_matcher_basic_check(en_vocab):
matcher = Matcher(en_vocab)
# Potential mistake: pass in pattern instead of list of patterns
@@ -669,3 +871,38 @@ def test_matcher_ent_iob_key(en_vocab):
assert matches[0] == "Maria"
assert matches[1] == "Maria Esperanza"
assert matches[2] == "Esperanza"
+
+
+def test_matcher_min_max_operator(en_vocab):
+ # Exactly n matches {n}
+ doc = Doc(
+ en_vocab,
+ words=["foo", "bar", "foo", "foo", "bar", "foo", "foo", "foo", "bar", "bar"],
+ )
+ matcher = Matcher(en_vocab)
+ pattern = [{"ORTH": "foo", "OP": "{3}"}]
+ matcher.add("TEST", [pattern])
+
+ matches1 = [doc[start:end].text for _, start, end in matcher(doc)]
+ assert len(matches1) == 1
+
+ # At least n matches {n,}
+ matcher = Matcher(en_vocab)
+ pattern = [{"ORTH": "foo", "OP": "{2,}"}]
+ matcher.add("TEST", [pattern])
+ matches2 = [doc[start:end].text for _, start, end in matcher(doc)]
+ assert len(matches2) == 4
+
+ # At most m matches {,m}
+ matcher = Matcher(en_vocab)
+ pattern = [{"ORTH": "foo", "OP": "{,2}"}]
+ matcher.add("TEST", [pattern])
+ matches3 = [doc[start:end].text for _, start, end in matcher(doc)]
+ assert len(matches3) == 9
+
+ # At least n matches and most m matches {n,m}
+ matcher = Matcher(en_vocab)
+ pattern = [{"ORTH": "foo", "OP": "{2,3}"}]
+ matcher.add("TEST", [pattern])
+ matches4 = [doc[start:end].text for _, start, end in matcher(doc)]
+ assert len(matches4) == 4
diff --git a/spacy/tests/matcher/test_matcher_logic.py b/spacy/tests/matcher/test_matcher_logic.py
index 3649b07ed..3b65fee23 100644
--- a/spacy/tests/matcher/test_matcher_logic.py
+++ b/spacy/tests/matcher/test_matcher_logic.py
@@ -699,6 +699,10 @@ def test_matcher_with_alignments_greedy_longest(en_vocab):
("aaaa", "a a a a a?", [0, 1, 2, 3]),
("aaab", "a+ a b", [0, 0, 1, 2]),
("aaab", "a+ a+ b", [0, 0, 1, 2]),
+ ("aaab", "a{2,} b", [0, 0, 0, 1]),
+ ("aaab", "a{,3} b", [0, 0, 0, 1]),
+ ("aaab", "a{2} b", [0, 0, 1]),
+ ("aaab", "a{2,3} b", [0, 0, 0, 1]),
]
for string, pattern_str, result in cases:
matcher = Matcher(en_vocab)
@@ -711,6 +715,8 @@ def test_matcher_with_alignments_greedy_longest(en_vocab):
pattern.append({"ORTH": part[0], "OP": "*"})
elif part.endswith("?"):
pattern.append({"ORTH": part[0], "OP": "?"})
+ elif part.endswith("}"):
+ pattern.append({"ORTH": part[0], "OP": part[1:]})
else:
pattern.append({"ORTH": part})
matcher.add("PATTERN", [pattern], greedy="LONGEST")
@@ -722,7 +728,7 @@ def test_matcher_with_alignments_greedy_longest(en_vocab):
assert expected == result, (string, pattern_str, s, e, n_matches)
-def test_matcher_with_alignments_nongreedy(en_vocab):
+def test_matcher_with_alignments_non_greedy(en_vocab):
cases = [
(0, "aaab", "a* b", [[0, 1], [0, 0, 1], [0, 0, 0, 1], [1]]),
(1, "baab", "b a* b", [[0, 1, 1, 2]]),
@@ -752,6 +758,10 @@ def test_matcher_with_alignments_nongreedy(en_vocab):
(15, "aaaa", "a a a a a?", [[0, 1, 2, 3]]),
(16, "aaab", "a+ a b", [[0, 1, 2], [0, 0, 1, 2]]),
(17, "aaab", "a+ a+ b", [[0, 1, 2], [0, 0, 1, 2]]),
+ (18, "aaab", "a{2,} b", [[0, 0, 1], [0, 0, 0, 1]]),
+ (19, "aaab", "a{3} b", [[0, 0, 0, 1]]),
+ (20, "aaab", "a{2} b", [[0, 0, 1]]),
+ (21, "aaab", "a{2,3} b", [[0, 0, 1], [0, 0, 0, 1]]),
]
for case_id, string, pattern_str, results in cases:
matcher = Matcher(en_vocab)
@@ -764,6 +774,8 @@ def test_matcher_with_alignments_nongreedy(en_vocab):
pattern.append({"ORTH": part[0], "OP": "*"})
elif part.endswith("?"):
pattern.append({"ORTH": part[0], "OP": "?"})
+ elif part.endswith("}"):
+ pattern.append({"ORTH": part[0], "OP": part[1:]})
else:
pattern.append({"ORTH": part})
diff --git a/spacy/tests/matcher/test_pattern_validation.py b/spacy/tests/matcher/test_pattern_validation.py
index 8c265785c..e7eced02c 100644
--- a/spacy/tests/matcher/test_pattern_validation.py
+++ b/spacy/tests/matcher/test_pattern_validation.py
@@ -14,6 +14,14 @@ TEST_PATTERNS = [
('[{"TEXT": "foo"}, {"LOWER": "bar"}]', 1, 1),
([{"ENT_IOB": "foo"}], 1, 1),
([1, 2, 3], 3, 1),
+ ([{"TEXT": "foo", "OP": "{,}"}], 1, 1),
+ ([{"TEXT": "foo", "OP": "{,4}4"}], 1, 1),
+ ([{"TEXT": "foo", "OP": "{a,3}"}], 1, 1),
+ ([{"TEXT": "foo", "OP": "{a}"}], 1, 1),
+ ([{"TEXT": "foo", "OP": "{,a}"}], 1, 1),
+ ([{"TEXT": "foo", "OP": "{1,2,3}"}], 1, 1),
+ ([{"TEXT": "foo", "OP": "{1, 3}"}], 1, 1),
+ ([{"TEXT": "foo", "OP": "{-2}"}], 1, 1),
# Bad patterns flagged outside of Matcher
([{"_": {"foo": "bar", "baz": {"IN": "foo"}}}], 2, 0), # prev: (1, 0)
# Bad patterns not flagged with minimal checks
@@ -38,6 +46,7 @@ TEST_PATTERNS = [
([{"SENT_START": True}], 0, 0),
([{"ENT_ID": "STRING"}], 0, 0),
([{"ENT_KB_ID": "STRING"}], 0, 0),
+ ([{"TEXT": "ha", "OP": "{3}"}], 0, 0),
]
diff --git a/spacy/tests/matcher/test_phrase_matcher.py b/spacy/tests/matcher/test_phrase_matcher.py
index f893d81f8..8a8d9eb84 100644
--- a/spacy/tests/matcher/test_phrase_matcher.py
+++ b/spacy/tests/matcher/test_phrase_matcher.py
@@ -1,4 +1,5 @@
import pytest
+import warnings
import srsly
from mock import Mock
@@ -122,6 +123,36 @@ def test_issue6839(en_vocab):
assert matches
+@pytest.mark.issue(10643)
+def test_issue10643(en_vocab):
+ """Ensure overlapping terms can be removed from PhraseMatcher"""
+
+ # fmt: off
+ words = ["Only", "save", "out", "the", "binary", "data", "for", "the", "individual", "components", "."]
+ # fmt: on
+ doc = Doc(en_vocab, words=words)
+ terms = {
+ "0": Doc(en_vocab, words=["binary"]),
+ "1": Doc(en_vocab, words=["binary", "data"]),
+ }
+ matcher = PhraseMatcher(en_vocab)
+ for match_id, term in terms.items():
+ matcher.add(match_id, [term])
+
+ matches = matcher(doc)
+ assert matches == [(en_vocab.strings["0"], 4, 5), (en_vocab.strings["1"], 4, 6)]
+
+ matcher.remove("0")
+ assert len(matcher) == 1
+ new_matches = matcher(doc)
+ assert new_matches == [(en_vocab.strings["1"], 4, 6)]
+
+ matcher.remove("1")
+ assert len(matcher) == 0
+ no_matches = matcher(doc)
+ assert not no_matches
+
+
def test_matcher_phrase_matcher(en_vocab):
doc = Doc(en_vocab, words=["I", "like", "Google", "Now", "best"])
# intermediate phrase
@@ -314,13 +345,13 @@ def test_phrase_matcher_validation(en_vocab):
matcher.add("TEST1", [doc1])
with pytest.warns(UserWarning):
matcher.add("TEST2", [doc2])
- with pytest.warns(None) as record:
+ with warnings.catch_warnings():
+ warnings.simplefilter("error")
matcher.add("TEST3", [doc3])
- assert not record.list
matcher = PhraseMatcher(en_vocab, attr="POS", validate=True)
- with pytest.warns(None) as record:
+ with warnings.catch_warnings():
+ warnings.simplefilter("error")
matcher.add("TEST4", [doc2])
- assert not record.list
def test_attr_validation(en_vocab):
diff --git a/spacy/tests/package/test_requirements.py b/spacy/tests/package/test_requirements.py
index e20227455..b403f274f 100644
--- a/spacy/tests/package/test_requirements.py
+++ b/spacy/tests/package/test_requirements.py
@@ -17,6 +17,7 @@ def test_build_dependencies():
"types-dataclasses",
"types-mock",
"types-requests",
+ "types-setuptools",
]
# ignore language-specific packages that shouldn't be installed by all
libs_ignore_setup = [
diff --git a/spacy/tests/parser/test_ner.py b/spacy/tests/parser/test_ner.py
index b3b29d1f9..00889efdc 100644
--- a/spacy/tests/parser/test_ner.py
+++ b/spacy/tests/parser/test_ner.py
@@ -10,7 +10,7 @@ from spacy.lang.it import Italian
from spacy.language import Language
from spacy.lookups import Lookups
from spacy.pipeline._parser_internals.ner import BiluoPushDown
-from spacy.training import Example, iob_to_biluo
+from spacy.training import Example, iob_to_biluo, split_bilu_label
from spacy.tokens import Doc, Span
from spacy.vocab import Vocab
import logging
@@ -110,6 +110,9 @@ def test_issue2385():
# maintain support for iob2 format
tags3 = ("B-PERSON", "I-PERSON", "B-PERSON")
assert iob_to_biluo(tags3) == ["B-PERSON", "L-PERSON", "U-PERSON"]
+ # ensure it works with hyphens in the name
+ tags4 = ("B-MULTI-PERSON", "I-MULTI-PERSON", "B-MULTI-PERSON")
+ assert iob_to_biluo(tags4) == ["B-MULTI-PERSON", "L-MULTI-PERSON", "U-MULTI-PERSON"]
@pytest.mark.issue(2800)
@@ -154,6 +157,24 @@ def test_issue3209():
assert ner2.move_names == move_names
+def test_labels_from_BILUO():
+ """Test that labels are inferred correctly when there's a - in label."""
+ nlp = English()
+ ner = nlp.add_pipe("ner")
+ ner.add_label("LARGE-ANIMAL")
+ nlp.initialize()
+ move_names = [
+ "O",
+ "B-LARGE-ANIMAL",
+ "I-LARGE-ANIMAL",
+ "L-LARGE-ANIMAL",
+ "U-LARGE-ANIMAL",
+ ]
+ labels = {"LARGE-ANIMAL"}
+ assert ner.move_names == move_names
+ assert set(ner.labels) == labels
+
+
@pytest.mark.issue(4267)
def test_issue4267():
"""Test that running an entity_ruler after ner gives consistent results"""
@@ -298,7 +319,7 @@ def test_oracle_moves_missing_B(en_vocab):
elif tag == "O":
moves.add_action(move_types.index("O"), "")
else:
- action, label = tag.split("-")
+ action, label = split_bilu_label(tag)
moves.add_action(move_types.index("B"), label)
moves.add_action(move_types.index("I"), label)
moves.add_action(move_types.index("L"), label)
@@ -324,7 +345,7 @@ def test_oracle_moves_whitespace(en_vocab):
elif tag == "O":
moves.add_action(move_types.index("O"), "")
else:
- action, label = tag.split("-")
+ action, label = split_bilu_label(tag)
moves.add_action(move_types.index(action), label)
moves.get_oracle_sequence(example)
diff --git a/spacy/tests/parser/test_nonproj.py b/spacy/tests/parser/test_nonproj.py
index 60d000c44..051d0ef0c 100644
--- a/spacy/tests/parser/test_nonproj.py
+++ b/spacy/tests/parser/test_nonproj.py
@@ -49,7 +49,9 @@ def test_parser_contains_cycle(tree, cyclic_tree, partial_tree, multirooted_tree
assert contains_cycle(multirooted_tree) is None
-def test_parser_is_nonproj_arc(nonproj_tree, partial_tree, multirooted_tree):
+def test_parser_is_nonproj_arc(
+ cyclic_tree, nonproj_tree, partial_tree, multirooted_tree
+):
assert is_nonproj_arc(0, nonproj_tree) is False
assert is_nonproj_arc(1, nonproj_tree) is False
assert is_nonproj_arc(2, nonproj_tree) is False
@@ -62,15 +64,23 @@ def test_parser_is_nonproj_arc(nonproj_tree, partial_tree, multirooted_tree):
assert is_nonproj_arc(7, partial_tree) is False
assert is_nonproj_arc(17, multirooted_tree) is False
assert is_nonproj_arc(16, multirooted_tree) is True
+ with pytest.raises(
+ ValueError, match=r"Found cycle in dependency graph: \[1, 2, 2, 4, 5, 3, 2\]"
+ ):
+ is_nonproj_arc(6, cyclic_tree)
def test_parser_is_nonproj_tree(
- proj_tree, nonproj_tree, partial_tree, multirooted_tree
+ proj_tree, cyclic_tree, nonproj_tree, partial_tree, multirooted_tree
):
assert is_nonproj_tree(proj_tree) is False
assert is_nonproj_tree(nonproj_tree) is True
assert is_nonproj_tree(partial_tree) is False
assert is_nonproj_tree(multirooted_tree) is True
+ with pytest.raises(
+ ValueError, match=r"Found cycle in dependency graph: \[1, 2, 2, 4, 5, 3, 2\]"
+ ):
+ is_nonproj_tree(cyclic_tree)
def test_parser_pseudoprojectivity(en_vocab):
@@ -84,8 +94,10 @@ def test_parser_pseudoprojectivity(en_vocab):
tree = [1, 2, 2]
nonproj_tree = [1, 2, 2, 4, 5, 2, 7, 4, 2]
nonproj_tree2 = [9, 1, 3, 1, 5, 6, 9, 8, 6, 1, 6, 12, 13, 10, 1]
+ cyclic_tree = [1, 2, 2, 4, 5, 3, 2]
labels = ["det", "nsubj", "root", "det", "dobj", "aux", "nsubj", "acl", "punct"]
labels2 = ["advmod", "root", "det", "nsubj", "advmod", "det", "dobj", "det", "nmod", "aux", "nmod", "advmod", "det", "amod", "punct"]
+ cyclic_labels = ["det", "nsubj", "root", "det", "dobj", "aux", "punct"]
# fmt: on
assert nonproj.decompose("X||Y") == ("X", "Y")
assert nonproj.decompose("X") == ("X", "")
@@ -97,6 +109,8 @@ def test_parser_pseudoprojectivity(en_vocab):
assert nonproj.get_smallest_nonproj_arc_slow(nonproj_tree2) == 10
# fmt: off
proj_heads, deco_labels = nonproj.projectivize(nonproj_tree, labels)
+ with pytest.raises(ValueError, match=r'Found cycle in dependency graph: \[1, 2, 2, 4, 5, 3, 2\]'):
+ nonproj.projectivize(cyclic_tree, cyclic_labels)
assert proj_heads == [1, 2, 2, 4, 5, 2, 7, 5, 2]
assert deco_labels == ["det", "nsubj", "root", "det", "dobj", "aux",
"nsubj", "acl||dobj", "punct"]
diff --git a/spacy/tests/parser/test_parse.py b/spacy/tests/parser/test_parse.py
index 7bbb30d8e..aaf31ed56 100644
--- a/spacy/tests/parser/test_parse.py
+++ b/spacy/tests/parser/test_parse.py
@@ -12,6 +12,7 @@ from spacy.vocab import Vocab
from ...pipeline import DependencyParser
from ...pipeline.dep_parser import DEFAULT_PARSER_MODEL
from ..util import apply_transition_sequence, make_tempdir
+from ...pipeline.tok2vec import DEFAULT_TOK2VEC_MODEL
TRAIN_DATA = [
(
@@ -395,6 +396,34 @@ def test_overfitting_IO(pipe_name):
assert_equal(batch_deps_1, no_batch_deps)
+# fmt: off
+@pytest.mark.slow
+@pytest.mark.parametrize("pipe_name", ["parser", "beam_parser"])
+@pytest.mark.parametrize(
+ "parser_config",
+ [
+ # TransitionBasedParser V1
+ ({"@architectures": "spacy.TransitionBasedParser.v1", "tok2vec": DEFAULT_TOK2VEC_MODEL, "state_type": "parser", "extra_state_tokens": False, "hidden_width": 64, "maxout_pieces": 2, "use_upper": True}),
+ # TransitionBasedParser V2
+ ({"@architectures": "spacy.TransitionBasedParser.v2", "tok2vec": DEFAULT_TOK2VEC_MODEL, "state_type": "parser", "extra_state_tokens": False, "hidden_width": 64, "maxout_pieces": 2, "use_upper": True}),
+ ],
+)
+# fmt: on
+def test_parser_configs(pipe_name, parser_config):
+ pipe_config = {"model": parser_config}
+ nlp = English()
+ parser = nlp.add_pipe(pipe_name, config=pipe_config)
+ train_examples = []
+ for text, annotations in TRAIN_DATA:
+ train_examples.append(Example.from_dict(nlp.make_doc(text), annotations))
+ for dep in annotations.get("deps", []):
+ parser.add_label(dep)
+ optimizer = nlp.initialize()
+ for i in range(5):
+ losses = {}
+ nlp.update(train_examples, sgd=optimizer, losses=losses)
+
+
def test_beam_parser_scores():
# Test that we can get confidence values out of the beam_parser pipe
beam_width = 16
diff --git a/spacy/tests/pipeline/test_edit_tree_lemmatizer.py b/spacy/tests/pipeline/test_edit_tree_lemmatizer.py
new file mode 100644
index 000000000..128d75680
--- /dev/null
+++ b/spacy/tests/pipeline/test_edit_tree_lemmatizer.py
@@ -0,0 +1,332 @@
+import pickle
+import pytest
+from hypothesis import given
+import hypothesis.strategies as st
+from spacy import util
+from spacy.lang.en import English
+from spacy.language import Language
+from spacy.pipeline._edit_tree_internals.edit_trees import EditTrees
+from spacy.training import Example
+from spacy.strings import StringStore
+from spacy.util import make_tempdir
+
+
+TRAIN_DATA = [
+ ("She likes green eggs", {"lemmas": ["she", "like", "green", "egg"]}),
+ ("Eat blue ham", {"lemmas": ["eat", "blue", "ham"]}),
+]
+
+PARTIAL_DATA = [
+ # partial annotation
+ ("She likes green eggs", {"lemmas": ["", "like", "green", ""]}),
+ # misaligned partial annotation
+ (
+ "He hates green eggs",
+ {
+ "words": ["He", "hat", "es", "green", "eggs"],
+ "lemmas": ["", "hat", "e", "green", ""],
+ },
+ ),
+]
+
+
+def test_initialize_examples():
+ nlp = Language()
+ lemmatizer = nlp.add_pipe("trainable_lemmatizer")
+ train_examples = []
+ for t in TRAIN_DATA:
+ train_examples.append(Example.from_dict(nlp.make_doc(t[0]), t[1]))
+ # you shouldn't really call this more than once, but for testing it should be fine
+ nlp.initialize(get_examples=lambda: train_examples)
+ with pytest.raises(TypeError):
+ nlp.initialize(get_examples=lambda: None)
+ with pytest.raises(TypeError):
+ nlp.initialize(get_examples=lambda: train_examples[0])
+ with pytest.raises(TypeError):
+ nlp.initialize(get_examples=lambda: [])
+ with pytest.raises(TypeError):
+ nlp.initialize(get_examples=train_examples)
+
+
+def test_initialize_from_labels():
+ nlp = Language()
+ lemmatizer = nlp.add_pipe("trainable_lemmatizer")
+ lemmatizer.min_tree_freq = 1
+ train_examples = []
+ for t in TRAIN_DATA:
+ train_examples.append(Example.from_dict(nlp.make_doc(t[0]), t[1]))
+ nlp.initialize(get_examples=lambda: train_examples)
+
+ nlp2 = Language()
+ lemmatizer2 = nlp2.add_pipe("trainable_lemmatizer")
+ lemmatizer2.initialize(
+ # We want to check that the strings in replacement nodes are
+ # added to the string store. Avoid that they get added through
+ # the examples.
+ get_examples=lambda: train_examples[:1],
+ labels=lemmatizer.label_data,
+ )
+ assert lemmatizer2.tree2label == {1: 0, 3: 1, 4: 2, 6: 3}
+ assert lemmatizer2.label_data == {
+ "trees": [
+ {"orig": "S", "subst": "s"},
+ {
+ "prefix_len": 1,
+ "suffix_len": 0,
+ "prefix_tree": 0,
+ "suffix_tree": 4294967295,
+ },
+ {"orig": "s", "subst": ""},
+ {
+ "prefix_len": 0,
+ "suffix_len": 1,
+ "prefix_tree": 4294967295,
+ "suffix_tree": 2,
+ },
+ {
+ "prefix_len": 0,
+ "suffix_len": 0,
+ "prefix_tree": 4294967295,
+ "suffix_tree": 4294967295,
+ },
+ {"orig": "E", "subst": "e"},
+ {
+ "prefix_len": 1,
+ "suffix_len": 0,
+ "prefix_tree": 5,
+ "suffix_tree": 4294967295,
+ },
+ ],
+ "labels": (1, 3, 4, 6),
+ }
+
+
+@pytest.mark.parametrize("top_k", (1, 5, 30))
+def test_no_data(top_k):
+ # Test that the lemmatizer provides a nice error when there's no tagging data / labels
+ TEXTCAT_DATA = [
+ ("I'm so happy.", {"cats": {"POSITIVE": 1.0, "NEGATIVE": 0.0}}),
+ ("I'm so angry", {"cats": {"POSITIVE": 0.0, "NEGATIVE": 1.0}}),
+ ]
+ nlp = English()
+ nlp.add_pipe("trainable_lemmatizer", config={"top_k": top_k})
+ nlp.add_pipe("textcat")
+
+ train_examples = []
+ for t in TEXTCAT_DATA:
+ train_examples.append(Example.from_dict(nlp.make_doc(t[0]), t[1]))
+
+ with pytest.raises(ValueError):
+ nlp.initialize(get_examples=lambda: train_examples)
+
+
+@pytest.mark.parametrize("top_k", (1, 5, 30))
+def test_incomplete_data(top_k):
+ # Test that the lemmatizer works with incomplete information
+ nlp = English()
+ lemmatizer = nlp.add_pipe("trainable_lemmatizer", config={"top_k": top_k})
+ lemmatizer.min_tree_freq = 1
+ train_examples = []
+ for t in PARTIAL_DATA:
+ train_examples.append(Example.from_dict(nlp.make_doc(t[0]), t[1]))
+ optimizer = nlp.initialize(get_examples=lambda: train_examples)
+ for i in range(50):
+ losses = {}
+ nlp.update(train_examples, sgd=optimizer, losses=losses)
+ assert losses["trainable_lemmatizer"] < 0.00001
+
+ # test the trained model
+ test_text = "She likes blue eggs"
+ doc = nlp(test_text)
+ assert doc[1].lemma_ == "like"
+ assert doc[2].lemma_ == "blue"
+
+ # Check that incomplete annotations are ignored.
+ scores, _ = lemmatizer.model([eg.predicted for eg in train_examples], is_train=True)
+ _, dX = lemmatizer.get_loss(train_examples, scores)
+ xp = lemmatizer.model.ops.xp
+
+ # Missing annotations.
+ assert xp.count_nonzero(dX[0][0]) == 0
+ assert xp.count_nonzero(dX[0][3]) == 0
+ assert xp.count_nonzero(dX[1][0]) == 0
+ assert xp.count_nonzero(dX[1][3]) == 0
+
+ # Misaligned annotations.
+ assert xp.count_nonzero(dX[1][1]) == 0
+
+
+@pytest.mark.parametrize("top_k", (1, 5, 30))
+def test_overfitting_IO(top_k):
+ nlp = English()
+ lemmatizer = nlp.add_pipe("trainable_lemmatizer", config={"top_k": top_k})
+ lemmatizer.min_tree_freq = 1
+ train_examples = []
+ for t in TRAIN_DATA:
+ train_examples.append(Example.from_dict(nlp.make_doc(t[0]), t[1]))
+
+ optimizer = nlp.initialize(get_examples=lambda: train_examples)
+
+ for i in range(50):
+ losses = {}
+ nlp.update(train_examples, sgd=optimizer, losses=losses)
+ assert losses["trainable_lemmatizer"] < 0.00001
+
+ test_text = "She likes blue eggs"
+ doc = nlp(test_text)
+ assert doc[0].lemma_ == "she"
+ assert doc[1].lemma_ == "like"
+ assert doc[2].lemma_ == "blue"
+ assert doc[3].lemma_ == "egg"
+
+ # Check model after a {to,from}_disk roundtrip
+ with util.make_tempdir() as tmp_dir:
+ nlp.to_disk(tmp_dir)
+ nlp2 = util.load_model_from_path(tmp_dir)
+ doc2 = nlp2(test_text)
+ assert doc2[0].lemma_ == "she"
+ assert doc2[1].lemma_ == "like"
+ assert doc2[2].lemma_ == "blue"
+ assert doc2[3].lemma_ == "egg"
+
+ # Check model after a {to,from}_bytes roundtrip
+ nlp_bytes = nlp.to_bytes()
+ nlp3 = English()
+ nlp3.add_pipe("trainable_lemmatizer", config={"top_k": top_k})
+ nlp3.from_bytes(nlp_bytes)
+ doc3 = nlp3(test_text)
+ assert doc3[0].lemma_ == "she"
+ assert doc3[1].lemma_ == "like"
+ assert doc3[2].lemma_ == "blue"
+ assert doc3[3].lemma_ == "egg"
+
+ # Check model after a pickle roundtrip.
+ nlp_bytes = pickle.dumps(nlp)
+ nlp4 = pickle.loads(nlp_bytes)
+ doc4 = nlp4(test_text)
+ assert doc4[0].lemma_ == "she"
+ assert doc4[1].lemma_ == "like"
+ assert doc4[2].lemma_ == "blue"
+ assert doc4[3].lemma_ == "egg"
+
+
+def test_lemmatizer_requires_labels():
+ nlp = English()
+ nlp.add_pipe("trainable_lemmatizer")
+ with pytest.raises(ValueError):
+ nlp.initialize()
+
+
+def test_lemmatizer_label_data():
+ nlp = English()
+ lemmatizer = nlp.add_pipe("trainable_lemmatizer")
+ lemmatizer.min_tree_freq = 1
+ train_examples = []
+ for t in TRAIN_DATA:
+ train_examples.append(Example.from_dict(nlp.make_doc(t[0]), t[1]))
+
+ nlp.initialize(get_examples=lambda: train_examples)
+
+ nlp2 = English()
+ lemmatizer2 = nlp2.add_pipe("trainable_lemmatizer")
+ lemmatizer2.initialize(
+ get_examples=lambda: train_examples, labels=lemmatizer.label_data
+ )
+
+ # Verify that the labels and trees are the same.
+ assert lemmatizer.labels == lemmatizer2.labels
+ assert lemmatizer.trees.to_bytes() == lemmatizer2.trees.to_bytes()
+
+
+def test_dutch():
+ strings = StringStore()
+ trees = EditTrees(strings)
+ tree = trees.add("deelt", "delen")
+ assert trees.tree_to_str(tree) == "(m 0 3 () (m 0 2 (s '' 'l') (s 'lt' 'n')))"
+
+ tree = trees.add("gedeeld", "delen")
+ assert (
+ trees.tree_to_str(tree) == "(m 2 3 (s 'ge' '') (m 0 2 (s '' 'l') (s 'ld' 'n')))"
+ )
+
+
+def test_from_to_bytes():
+ strings = StringStore()
+ trees = EditTrees(strings)
+ trees.add("deelt", "delen")
+ trees.add("gedeeld", "delen")
+
+ b = trees.to_bytes()
+
+ trees2 = EditTrees(strings)
+ trees2.from_bytes(b)
+
+ # Verify that the nodes did not change.
+ assert len(trees) == len(trees2)
+ for i in range(len(trees)):
+ assert trees.tree_to_str(i) == trees2.tree_to_str(i)
+
+ # Reinserting the same trees should not add new nodes.
+ trees2.add("deelt", "delen")
+ trees2.add("gedeeld", "delen")
+ assert len(trees) == len(trees2)
+
+
+def test_from_to_disk():
+ strings = StringStore()
+ trees = EditTrees(strings)
+ trees.add("deelt", "delen")
+ trees.add("gedeeld", "delen")
+
+ trees2 = EditTrees(strings)
+ with make_tempdir() as temp_dir:
+ trees_file = temp_dir / "edit_trees.bin"
+ trees.to_disk(trees_file)
+ trees2 = trees2.from_disk(trees_file)
+
+ # Verify that the nodes did not change.
+ assert len(trees) == len(trees2)
+ for i in range(len(trees)):
+ assert trees.tree_to_str(i) == trees2.tree_to_str(i)
+
+ # Reinserting the same trees should not add new nodes.
+ trees2.add("deelt", "delen")
+ trees2.add("gedeeld", "delen")
+ assert len(trees) == len(trees2)
+
+
+@given(st.text(), st.text())
+def test_roundtrip(form, lemma):
+ strings = StringStore()
+ trees = EditTrees(strings)
+ tree = trees.add(form, lemma)
+ assert trees.apply(tree, form) == lemma
+
+
+@given(st.text(alphabet="ab"), st.text(alphabet="ab"))
+def test_roundtrip_small_alphabet(form, lemma):
+ # Test with small alphabets to have more overlap.
+ strings = StringStore()
+ trees = EditTrees(strings)
+ tree = trees.add(form, lemma)
+ assert trees.apply(tree, form) == lemma
+
+
+def test_unapplicable_trees():
+ strings = StringStore()
+ trees = EditTrees(strings)
+ tree3 = trees.add("deelt", "delen")
+
+ # Replacement fails.
+ assert trees.apply(tree3, "deeld") == None
+
+ # Suffix + prefix are too large.
+ assert trees.apply(tree3, "de") == None
+
+
+def test_empty_strings():
+ strings = StringStore()
+ trees = EditTrees(strings)
+ no_change = trees.add("xyz", "xyz")
+ empty = trees.add("", "")
+ assert no_change == empty
diff --git a/spacy/tests/pipeline/test_entity_linker.py b/spacy/tests/pipeline/test_entity_linker.py
index 3740e430e..99f164f15 100644
--- a/spacy/tests/pipeline/test_entity_linker.py
+++ b/spacy/tests/pipeline/test_entity_linker.py
@@ -1,4 +1,4 @@
-from typing import Callable, Iterable
+from typing import Callable, Iterable, Dict, Any
import pytest
from numpy.testing import assert_equal
@@ -6,12 +6,16 @@ from numpy.testing import assert_equal
from spacy import registry, util
from spacy.attrs import ENT_KB_ID
from spacy.compat import pickle
-from spacy.kb import Candidate, KnowledgeBase, get_candidates
+from spacy.kb import Candidate, InMemoryLookupKB, get_candidates, KnowledgeBase
from spacy.lang.en import English
from spacy.ml import load_kb
+from spacy.ml.models.entity_linker import build_span_maker
+from spacy.pipeline import EntityLinker
+from spacy.pipeline.legacy import EntityLinker_v1
+from spacy.pipeline.tok2vec import DEFAULT_TOK2VEC_MODEL
from spacy.scorer import Scorer
from spacy.tests.util import make_tempdir
-from spacy.tokens import Span
+from spacy.tokens import Span, Doc
from spacy.training import Example
from spacy.util import ensure_path
from spacy.vocab import Vocab
@@ -31,7 +35,7 @@ def assert_almost_equal(a, b):
def test_issue4674():
"""Test that setting entities with overlapping identifiers does not mess up IO"""
nlp = English()
- kb = KnowledgeBase(nlp.vocab, entity_vector_length=3)
+ kb = InMemoryLookupKB(nlp.vocab, entity_vector_length=3)
vector1 = [0.9, 1.1, 1.01]
vector2 = [1.8, 2.25, 2.01]
with pytest.warns(UserWarning):
@@ -48,7 +52,7 @@ def test_issue4674():
dir_path.mkdir()
file_path = dir_path / "kb"
kb.to_disk(str(file_path))
- kb2 = KnowledgeBase(nlp.vocab, entity_vector_length=3)
+ kb2 = InMemoryLookupKB(nlp.vocab, entity_vector_length=3)
kb2.from_disk(str(file_path))
assert kb2.get_size_entities() == 1
@@ -56,9 +60,9 @@ def test_issue4674():
@pytest.mark.issue(6730)
def test_issue6730(en_vocab):
"""Ensure that the KB does not accept empty strings, but otherwise IO works fine."""
- from spacy.kb import KnowledgeBase
+ from spacy.kb.kb_in_memory import InMemoryLookupKB
- kb = KnowledgeBase(en_vocab, entity_vector_length=3)
+ kb = InMemoryLookupKB(en_vocab, entity_vector_length=3)
kb.add_entity(entity="1", freq=148, entity_vector=[1, 2, 3])
with pytest.raises(ValueError):
@@ -124,7 +128,7 @@ def test_issue7065_b():
def create_kb(vocab):
# create artificial KB
- mykb = KnowledgeBase(vocab, entity_vector_length=vector_length)
+ mykb = InMemoryLookupKB(vocab, entity_vector_length=vector_length)
mykb.add_entity(entity="Q270853", freq=12, entity_vector=[9, 1, -7])
mykb.add_alias(
alias="No. 8",
@@ -168,6 +172,45 @@ def test_issue7065_b():
assert doc
+def test_no_entities():
+ # Test that having no entities doesn't crash the model
+ TRAIN_DATA = [
+ (
+ "The sky is blue.",
+ {
+ "sent_starts": [1, 0, 0, 0, 0],
+ },
+ )
+ ]
+ nlp = English()
+ vector_length = 3
+ train_examples = []
+ for text, annotation in TRAIN_DATA:
+ doc = nlp(text)
+ train_examples.append(Example.from_dict(doc, annotation))
+
+ def create_kb(vocab):
+ # create artificial KB
+ mykb = InMemoryLookupKB(vocab, entity_vector_length=vector_length)
+ mykb.add_entity(entity="Q2146908", freq=12, entity_vector=[6, -4, 3])
+ mykb.add_alias("Russ Cochran", ["Q2146908"], [0.9])
+ return mykb
+
+ # Create and train the Entity Linker
+ entity_linker = nlp.add_pipe("entity_linker", last=True)
+ entity_linker.set_kb(create_kb)
+ optimizer = nlp.initialize(get_examples=lambda: train_examples)
+ for i in range(2):
+ losses = {}
+ nlp.update(train_examples, sgd=optimizer, losses=losses)
+
+ # adding additional components that are required for the entity_linker
+ nlp.add_pipe("sentencizer", first=True)
+
+ # this will run the pipeline on the examples and shouldn't crash
+ nlp.evaluate(train_examples)
+
+
def test_partial_links():
# Test that having some entities on the doc without gold links, doesn't crash
TRAIN_DATA = [
@@ -189,7 +232,7 @@ def test_partial_links():
def create_kb(vocab):
# create artificial KB
- mykb = KnowledgeBase(vocab, entity_vector_length=vector_length)
+ mykb = InMemoryLookupKB(vocab, entity_vector_length=vector_length)
mykb.add_entity(entity="Q2146908", freq=12, entity_vector=[6, -4, 3])
mykb.add_alias("Russ Cochran", ["Q2146908"], [0.9])
return mykb
@@ -221,7 +264,7 @@ def test_partial_links():
def test_kb_valid_entities(nlp):
"""Test the valid construction of a KB with 3 entities and two aliases"""
- mykb = KnowledgeBase(nlp.vocab, entity_vector_length=3)
+ mykb = InMemoryLookupKB(nlp.vocab, entity_vector_length=3)
# adding entities
mykb.add_entity(entity="Q1", freq=19, entity_vector=[8, 4, 3])
@@ -250,7 +293,7 @@ def test_kb_valid_entities(nlp):
def test_kb_invalid_entities(nlp):
"""Test the invalid construction of a KB with an alias linked to a non-existing entity"""
- mykb = KnowledgeBase(nlp.vocab, entity_vector_length=1)
+ mykb = InMemoryLookupKB(nlp.vocab, entity_vector_length=1)
# adding entities
mykb.add_entity(entity="Q1", freq=19, entity_vector=[1])
@@ -266,7 +309,7 @@ def test_kb_invalid_entities(nlp):
def test_kb_invalid_probabilities(nlp):
"""Test the invalid construction of a KB with wrong prior probabilities"""
- mykb = KnowledgeBase(nlp.vocab, entity_vector_length=1)
+ mykb = InMemoryLookupKB(nlp.vocab, entity_vector_length=1)
# adding entities
mykb.add_entity(entity="Q1", freq=19, entity_vector=[1])
@@ -280,7 +323,7 @@ def test_kb_invalid_probabilities(nlp):
def test_kb_invalid_combination(nlp):
"""Test the invalid construction of a KB with non-matching entity and probability lists"""
- mykb = KnowledgeBase(nlp.vocab, entity_vector_length=1)
+ mykb = InMemoryLookupKB(nlp.vocab, entity_vector_length=1)
# adding entities
mykb.add_entity(entity="Q1", freq=19, entity_vector=[1])
@@ -296,7 +339,7 @@ def test_kb_invalid_combination(nlp):
def test_kb_invalid_entity_vector(nlp):
"""Test the invalid construction of a KB with non-matching entity vector lengths"""
- mykb = KnowledgeBase(nlp.vocab, entity_vector_length=3)
+ mykb = InMemoryLookupKB(nlp.vocab, entity_vector_length=3)
# adding entities
mykb.add_entity(entity="Q1", freq=19, entity_vector=[1, 2, 3])
@@ -334,7 +377,7 @@ def test_kb_initialize_empty(nlp):
def test_kb_serialize(nlp):
"""Test serialization of the KB"""
- mykb = KnowledgeBase(nlp.vocab, entity_vector_length=1)
+ mykb = InMemoryLookupKB(nlp.vocab, entity_vector_length=1)
with make_tempdir() as d:
# normal read-write behaviour
mykb.to_disk(d / "kb")
@@ -351,12 +394,12 @@ def test_kb_serialize(nlp):
@pytest.mark.issue(9137)
def test_kb_serialize_2(nlp):
v = [5, 6, 7, 8]
- kb1 = KnowledgeBase(vocab=nlp.vocab, entity_vector_length=4)
+ kb1 = InMemoryLookupKB(vocab=nlp.vocab, entity_vector_length=4)
kb1.set_entities(["E1"], [1], [v])
assert kb1.get_vector("E1") == v
with make_tempdir() as d:
kb1.to_disk(d / "kb")
- kb2 = KnowledgeBase(vocab=nlp.vocab, entity_vector_length=4)
+ kb2 = InMemoryLookupKB(vocab=nlp.vocab, entity_vector_length=4)
kb2.from_disk(d / "kb")
assert kb2.get_vector("E1") == v
@@ -366,7 +409,7 @@ def test_kb_set_entities(nlp):
v = [5, 6, 7, 8]
v1 = [1, 1, 1, 0]
v2 = [2, 2, 2, 3]
- kb1 = KnowledgeBase(vocab=nlp.vocab, entity_vector_length=4)
+ kb1 = InMemoryLookupKB(vocab=nlp.vocab, entity_vector_length=4)
kb1.set_entities(["E0"], [1], [v])
assert kb1.get_entity_strings() == ["E0"]
kb1.set_entities(["E1", "E2"], [1, 9], [v1, v2])
@@ -375,7 +418,7 @@ def test_kb_set_entities(nlp):
assert kb1.get_vector("E2") == v2
with make_tempdir() as d:
kb1.to_disk(d / "kb")
- kb2 = KnowledgeBase(vocab=nlp.vocab, entity_vector_length=4)
+ kb2 = InMemoryLookupKB(vocab=nlp.vocab, entity_vector_length=4)
kb2.from_disk(d / "kb")
assert set(kb2.get_entity_strings()) == {"E1", "E2"}
assert kb2.get_vector("E1") == v1
@@ -386,7 +429,7 @@ def test_kb_serialize_vocab(nlp):
"""Test serialization of the KB and custom strings"""
entity = "MyFunnyID"
assert entity not in nlp.vocab.strings
- mykb = KnowledgeBase(nlp.vocab, entity_vector_length=1)
+ mykb = InMemoryLookupKB(nlp.vocab, entity_vector_length=1)
assert not mykb.contains_entity(entity)
mykb.add_entity(entity, freq=342, entity_vector=[3])
assert mykb.contains_entity(entity)
@@ -394,14 +437,14 @@ def test_kb_serialize_vocab(nlp):
with make_tempdir() as d:
# normal read-write behaviour
mykb.to_disk(d / "kb")
- mykb_new = KnowledgeBase(Vocab(), entity_vector_length=1)
+ mykb_new = InMemoryLookupKB(Vocab(), entity_vector_length=1)
mykb_new.from_disk(d / "kb")
assert entity in mykb_new.vocab.strings
def test_candidate_generation(nlp):
"""Test correct candidate generation"""
- mykb = KnowledgeBase(nlp.vocab, entity_vector_length=1)
+ mykb = InMemoryLookupKB(nlp.vocab, entity_vector_length=1)
doc = nlp("douglas adam Adam shrubbery")
douglas_ent = doc[0:1]
@@ -439,7 +482,7 @@ def test_el_pipe_configuration(nlp):
ruler.add_patterns([pattern])
def create_kb(vocab):
- kb = KnowledgeBase(vocab, entity_vector_length=1)
+ kb = InMemoryLookupKB(vocab, entity_vector_length=1)
kb.add_entity(entity="Q2", freq=12, entity_vector=[2])
kb.add_entity(entity="Q3", freq=5, entity_vector=[3])
kb.add_alias(alias="douglas", entities=["Q2", "Q3"], probabilities=[0.8, 0.1])
@@ -458,10 +501,21 @@ def test_el_pipe_configuration(nlp):
def get_lowercased_candidates(kb, span):
return kb.get_alias_candidates(span.text.lower())
+ def get_lowercased_candidates_batch(kb, spans):
+ return [get_lowercased_candidates(kb, span) for span in spans]
+
@registry.misc("spacy.LowercaseCandidateGenerator.v1")
- def create_candidates() -> Callable[[KnowledgeBase, "Span"], Iterable[Candidate]]:
+ def create_candidates() -> Callable[
+ [InMemoryLookupKB, "Span"], Iterable[Candidate]
+ ]:
return get_lowercased_candidates
+ @registry.misc("spacy.LowercaseCandidateBatchGenerator.v1")
+ def create_candidates_batch() -> Callable[
+ [InMemoryLookupKB, Iterable["Span"]], Iterable[Iterable[Candidate]]
+ ]:
+ return get_lowercased_candidates_batch
+
# replace the pipe with a new one with with a different candidate generator
entity_linker = nlp.replace_pipe(
"entity_linker",
@@ -469,6 +523,9 @@ def test_el_pipe_configuration(nlp):
config={
"incl_context": False,
"get_candidates": {"@misc": "spacy.LowercaseCandidateGenerator.v1"},
+ "get_candidates_batch": {
+ "@misc": "spacy.LowercaseCandidateBatchGenerator.v1"
+ },
},
)
entity_linker.set_kb(create_kb)
@@ -490,7 +547,7 @@ def test_nel_nsents(nlp):
def test_vocab_serialization(nlp):
"""Test that string information is retained across storage"""
- mykb = KnowledgeBase(nlp.vocab, entity_vector_length=1)
+ mykb = InMemoryLookupKB(nlp.vocab, entity_vector_length=1)
# adding entities
mykb.add_entity(entity="Q1", freq=27, entity_vector=[1])
@@ -510,7 +567,7 @@ def test_vocab_serialization(nlp):
with make_tempdir() as d:
mykb.to_disk(d / "kb")
- kb_new_vocab = KnowledgeBase(Vocab(), entity_vector_length=1)
+ kb_new_vocab = InMemoryLookupKB(Vocab(), entity_vector_length=1)
kb_new_vocab.from_disk(d / "kb")
candidates = kb_new_vocab.get_alias_candidates("adam")
@@ -526,7 +583,7 @@ def test_vocab_serialization(nlp):
def test_append_alias(nlp):
"""Test that we can append additional alias-entity pairs"""
- mykb = KnowledgeBase(nlp.vocab, entity_vector_length=1)
+ mykb = InMemoryLookupKB(nlp.vocab, entity_vector_length=1)
# adding entities
mykb.add_entity(entity="Q1", freq=27, entity_vector=[1])
@@ -557,7 +614,7 @@ def test_append_alias(nlp):
@pytest.mark.filterwarnings("ignore:\\[W036")
def test_append_invalid_alias(nlp):
"""Test that append an alias will throw an error if prior probs are exceeding 1"""
- mykb = KnowledgeBase(nlp.vocab, entity_vector_length=1)
+ mykb = InMemoryLookupKB(nlp.vocab, entity_vector_length=1)
# adding entities
mykb.add_entity(entity="Q1", freq=27, entity_vector=[1])
@@ -579,7 +636,7 @@ def test_preserving_links_asdoc(nlp):
vector_length = 1
def create_kb(vocab):
- mykb = KnowledgeBase(vocab, entity_vector_length=vector_length)
+ mykb = InMemoryLookupKB(vocab, entity_vector_length=vector_length)
# adding entities
mykb.add_entity(entity="Q1", freq=19, entity_vector=[1])
mykb.add_entity(entity="Q2", freq=8, entity_vector=[1])
@@ -650,7 +707,7 @@ TRAIN_DATA = [
"sent_starts": [1, -1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]}),
("Russ Cochran his reprints include EC Comics.",
{"links": {(0, 12): {"Q7381115": 1.0, "Q2146908": 0.0}},
- "entities": [(0, 12, "PERSON")],
+ "entities": [(0, 12, "PERSON"), (34, 43, "ART")],
"sent_starts": [1, -1, 0, 0, 0, 0, 0, 0]}),
("Russ Cochran has been publishing comic art.",
{"links": {(0, 12): {"Q7381115": 1.0, "Q2146908": 0.0}},
@@ -659,7 +716,11 @@ TRAIN_DATA = [
("Russ Cochran was a member of University of Kentucky's golf team.",
{"links": {(0, 12): {"Q7381115": 0.0, "Q2146908": 1.0}},
"entities": [(0, 12, "PERSON"), (43, 51, "LOC")],
- "sent_starts": [1, -1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]})
+ "sent_starts": [1, -1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]}),
+ # having a blank instance shouldn't break things
+ ("The weather is nice today.",
+ {"links": {}, "entities": [],
+ "sent_starts": [1, -1, 0, 0, 0, 0]})
]
GOLD_entities = ["Q2146908", "Q7381115", "Q7381115", "Q2146908"]
# fmt: on
@@ -681,7 +742,7 @@ def test_overfitting_IO():
# create artificial KB - assign same prior weight to the two russ cochran's
# Q2146908 (Russ Cochran): American golfer
# Q7381115 (Russ Cochran): publisher
- mykb = KnowledgeBase(vocab, entity_vector_length=vector_length)
+ mykb = InMemoryLookupKB(vocab, entity_vector_length=vector_length)
mykb.add_entity(entity="Q2146908", freq=12, entity_vector=[6, -4, 3])
mykb.add_entity(entity="Q7381115", freq=12, entity_vector=[9, 1, -7])
mykb.add_alias(
@@ -693,6 +754,7 @@ def test_overfitting_IO():
# Create the Entity Linker component and add it to the pipeline
entity_linker = nlp.add_pipe("entity_linker", last=True)
+ assert isinstance(entity_linker, EntityLinker)
entity_linker.set_kb(create_kb)
assert "Q2146908" in entity_linker.vocab.strings
assert "Q2146908" in entity_linker.kb.vocab.strings
@@ -762,7 +824,7 @@ def test_kb_serialization():
kb_dir = tmp_dir / "kb"
nlp1 = English()
assert "Q2146908" not in nlp1.vocab.strings
- mykb = KnowledgeBase(nlp1.vocab, entity_vector_length=vector_length)
+ mykb = InMemoryLookupKB(nlp1.vocab, entity_vector_length=vector_length)
mykb.add_entity(entity="Q2146908", freq=12, entity_vector=[6, -4, 3])
mykb.add_alias(alias="Russ Cochran", entities=["Q2146908"], probabilities=[0.8])
assert "Q2146908" in nlp1.vocab.strings
@@ -785,7 +847,7 @@ def test_kb_serialization():
def test_kb_pickle():
# Test that the KB can be pickled
nlp = English()
- kb_1 = KnowledgeBase(nlp.vocab, entity_vector_length=3)
+ kb_1 = InMemoryLookupKB(nlp.vocab, entity_vector_length=3)
kb_1.add_entity(entity="Q2146908", freq=12, entity_vector=[6, -4, 3])
assert not kb_1.contains_alias("Russ Cochran")
kb_1.add_alias(alias="Russ Cochran", entities=["Q2146908"], probabilities=[0.8])
@@ -799,7 +861,7 @@ def test_kb_pickle():
def test_nel_pickle():
# Test that a pipeline with an EL component can be pickled
def create_kb(vocab):
- kb = KnowledgeBase(vocab, entity_vector_length=3)
+ kb = InMemoryLookupKB(vocab, entity_vector_length=3)
kb.add_entity(entity="Q2146908", freq=12, entity_vector=[6, -4, 3])
kb.add_alias(alias="Russ Cochran", entities=["Q2146908"], probabilities=[0.8])
return kb
@@ -821,7 +883,7 @@ def test_nel_pickle():
def test_kb_to_bytes():
# Test that the KB's to_bytes method works correctly
nlp = English()
- kb_1 = KnowledgeBase(nlp.vocab, entity_vector_length=3)
+ kb_1 = InMemoryLookupKB(nlp.vocab, entity_vector_length=3)
kb_1.add_entity(entity="Q2146908", freq=12, entity_vector=[6, -4, 3])
kb_1.add_entity(entity="Q66", freq=9, entity_vector=[1, 2, 3])
kb_1.add_alias(alias="Russ Cochran", entities=["Q2146908"], probabilities=[0.8])
@@ -831,7 +893,7 @@ def test_kb_to_bytes():
)
assert kb_1.contains_alias("Russ Cochran")
kb_bytes = kb_1.to_bytes()
- kb_2 = KnowledgeBase(nlp.vocab, entity_vector_length=3)
+ kb_2 = InMemoryLookupKB(nlp.vocab, entity_vector_length=3)
assert not kb_2.contains_alias("Russ Cochran")
kb_2 = kb_2.from_bytes(kb_bytes)
# check that both KBs are exactly the same
@@ -854,7 +916,7 @@ def test_kb_to_bytes():
def test_nel_to_bytes():
# Test that a pipeline with an EL component can be converted to bytes
def create_kb(vocab):
- kb = KnowledgeBase(vocab, entity_vector_length=3)
+ kb = InMemoryLookupKB(vocab, entity_vector_length=3)
kb.add_entity(entity="Q2146908", freq=12, entity_vector=[6, -4, 3])
kb.add_alias(alias="Russ Cochran", entities=["Q2146908"], probabilities=[0.8])
return kb
@@ -922,3 +984,235 @@ def test_scorer_links():
assert scores["nel_micro_p"] == 2 / 3
assert scores["nel_micro_r"] == 2 / 4
+
+
+# fmt: off
+@pytest.mark.parametrize(
+ "name,config",
+ [
+ ("entity_linker", {"@architectures": "spacy.EntityLinker.v1", "tok2vec": DEFAULT_TOK2VEC_MODEL}),
+ ("entity_linker", {"@architectures": "spacy.EntityLinker.v2", "tok2vec": DEFAULT_TOK2VEC_MODEL}),
+ ],
+)
+# fmt: on
+def test_legacy_architectures(name, config):
+ # Ensure that the legacy architectures still work
+ vector_length = 3
+ nlp = English()
+
+ train_examples = []
+ for text, annotation in TRAIN_DATA:
+ doc = nlp.make_doc(text)
+ train_examples.append(Example.from_dict(doc, annotation))
+
+ def create_kb(vocab):
+ mykb = InMemoryLookupKB(vocab, entity_vector_length=vector_length)
+ mykb.add_entity(entity="Q2146908", freq=12, entity_vector=[6, -4, 3])
+ mykb.add_entity(entity="Q7381115", freq=12, entity_vector=[9, 1, -7])
+ mykb.add_alias(
+ alias="Russ Cochran",
+ entities=["Q2146908", "Q7381115"],
+ probabilities=[0.5, 0.5],
+ )
+ return mykb
+
+ entity_linker = nlp.add_pipe(name, config={"model": config})
+ if config["@architectures"] == "spacy.EntityLinker.v1":
+ assert isinstance(entity_linker, EntityLinker_v1)
+ else:
+ assert isinstance(entity_linker, EntityLinker)
+ entity_linker.set_kb(create_kb)
+ optimizer = nlp.initialize(get_examples=lambda: train_examples)
+
+ for i in range(2):
+ losses = {}
+ nlp.update(train_examples, sgd=optimizer, losses=losses)
+
+
+@pytest.mark.parametrize(
+ "patterns",
+ [
+ # perfect case
+ [{"label": "CHARACTER", "pattern": "Kirby"}],
+ # typo for false negative
+ [{"label": "PERSON", "pattern": "Korby"}],
+ # random stuff for false positive
+ [{"label": "IS", "pattern": "is"}, {"label": "COLOR", "pattern": "pink"}],
+ ],
+)
+def test_no_gold_ents(patterns):
+ # test that annotating components work
+ TRAIN_DATA = [
+ (
+ "Kirby is pink",
+ {
+ "links": {(0, 5): {"Q613241": 1.0}},
+ "entities": [(0, 5, "CHARACTER")],
+ "sent_starts": [1, 0, 0],
+ },
+ )
+ ]
+ nlp = English()
+ vector_length = 3
+ train_examples = []
+ for text, annotation in TRAIN_DATA:
+ doc = nlp(text)
+ train_examples.append(Example.from_dict(doc, annotation))
+
+ # Create a ruler to mark entities
+ ruler = nlp.add_pipe("entity_ruler")
+ ruler.add_patterns(patterns)
+
+ # Apply ruler to examples. In a real pipeline this would be an annotating component.
+ for eg in train_examples:
+ eg.predicted = ruler(eg.predicted)
+
+ # Entity ruler is no longer needed (initialization below wipes out the
+ # patterns and causes warnings)
+ nlp.remove_pipe("entity_ruler")
+
+ def create_kb(vocab):
+ # create artificial KB
+ mykb = InMemoryLookupKB(vocab, entity_vector_length=vector_length)
+ mykb.add_entity(entity="Q613241", freq=12, entity_vector=[6, -4, 3])
+ mykb.add_alias("Kirby", ["Q613241"], [0.9])
+ # Placeholder
+ mykb.add_entity(entity="pink", freq=12, entity_vector=[7, 2, -5])
+ mykb.add_alias("pink", ["pink"], [0.9])
+ return mykb
+
+ # Create and train the Entity Linker
+ entity_linker = nlp.add_pipe(
+ "entity_linker", config={"use_gold_ents": False}, last=True
+ )
+ entity_linker.set_kb(create_kb)
+ assert entity_linker.use_gold_ents is False
+
+ optimizer = nlp.initialize(get_examples=lambda: train_examples)
+ for i in range(2):
+ losses = {}
+ nlp.update(train_examples, sgd=optimizer, losses=losses)
+
+ # adding additional components that are required for the entity_linker
+ nlp.add_pipe("sentencizer", first=True)
+
+ # this will run the pipeline on the examples and shouldn't crash
+ nlp.evaluate(train_examples)
+
+
+@pytest.mark.issue(9575)
+def test_tokenization_mismatch():
+ nlp = English()
+ # include a matching entity so that update isn't skipped
+ doc1 = Doc(
+ nlp.vocab,
+ words=["Kirby", "123456"],
+ spaces=[True, False],
+ ents=["B-CHARACTER", "B-CARDINAL"],
+ )
+ doc2 = Doc(
+ nlp.vocab,
+ words=["Kirby", "123", "456"],
+ spaces=[True, False, False],
+ ents=["B-CHARACTER", "B-CARDINAL", "B-CARDINAL"],
+ )
+
+ eg = Example(doc1, doc2)
+ train_examples = [eg]
+ vector_length = 3
+
+ def create_kb(vocab):
+ # create placeholder KB
+ mykb = InMemoryLookupKB(vocab, entity_vector_length=vector_length)
+ mykb.add_entity(entity="Q613241", freq=12, entity_vector=[6, -4, 3])
+ mykb.add_alias("Kirby", ["Q613241"], [0.9])
+ return mykb
+
+ entity_linker = nlp.add_pipe("entity_linker", last=True)
+ entity_linker.set_kb(create_kb)
+
+ optimizer = nlp.initialize(get_examples=lambda: train_examples)
+ for i in range(2):
+ losses = {}
+ nlp.update(train_examples, sgd=optimizer, losses=losses)
+
+ nlp.add_pipe("sentencizer", first=True)
+ nlp.evaluate(train_examples)
+
+
+def test_abstract_kb_instantiation():
+ """Test whether instantiation of abstract KB base class fails."""
+ with pytest.raises(TypeError):
+ KnowledgeBase(None, 3)
+
+
+# fmt: off
+@pytest.mark.parametrize(
+ "meet_threshold,config",
+ [
+ (False, {"@architectures": "spacy.EntityLinker.v2", "tok2vec": DEFAULT_TOK2VEC_MODEL}),
+ (True, {"@architectures": "spacy.EntityLinker.v2", "tok2vec": DEFAULT_TOK2VEC_MODEL}),
+ ],
+)
+# fmt: on
+def test_threshold(meet_threshold: bool, config: Dict[str, Any]):
+ """Tests abstention threshold.
+ meet_threshold (bool): Whether to configure NEL setup so that confidence threshold is met.
+ config (Dict[str, Any]): NEL architecture config.
+ """
+ nlp = English()
+ nlp.add_pipe("sentencizer")
+ text = "Mahler's Symphony No. 8 was beautiful."
+ entities = [(0, 6, "PERSON")]
+ links = {(0, 6): {"Q7304": 1.0}}
+ sent_starts = [1, -1, 0, 0, 0, 0, 0, 0, 0]
+ entity_id = "Q7304"
+ doc = nlp(text)
+ train_examples = [
+ Example.from_dict(
+ doc, {"entities": entities, "links": links, "sent_starts": sent_starts}
+ )
+ ]
+
+ def create_kb(vocab):
+ # create artificial KB
+ mykb = InMemoryLookupKB(vocab, entity_vector_length=3)
+ mykb.add_entity(entity=entity_id, freq=12, entity_vector=[6, -4, 3])
+ mykb.add_alias(
+ alias="Mahler",
+ entities=[entity_id],
+ probabilities=[1 if meet_threshold else 0.01],
+ )
+ return mykb
+
+ # Create the Entity Linker component and add it to the pipeline
+ entity_linker = nlp.add_pipe(
+ "entity_linker",
+ last=True,
+ config={"threshold": 0.99, "model": config},
+ )
+ entity_linker.set_kb(create_kb) # type: ignore
+ nlp.initialize(get_examples=lambda: train_examples)
+
+ # Add a custom rule-based component to mimick NER
+ ruler = nlp.add_pipe("entity_ruler", before="entity_linker")
+ ruler.add_patterns([{"label": "PERSON", "pattern": [{"LOWER": "mahler"}]}]) # type: ignore
+ doc = nlp(text)
+
+ assert len(doc.ents) == 1
+ assert doc.ents[0].kb_id_ == entity_id if meet_threshold else EntityLinker.NIL
+
+
+def test_span_maker_forward_with_empty():
+ """The forward pass of the span maker may have a doc with no entities."""
+ nlp = English()
+ doc1 = nlp("a b c")
+ ent = doc1[0:1]
+ ent.label_ = "X"
+ doc1.ents = [ent]
+ # no entities
+ doc2 = nlp("x y z")
+
+ # just to get a model
+ span_maker = build_span_maker()
+ span_maker([doc1, doc2], False)
diff --git a/spacy/tests/pipeline/test_entity_ruler.py b/spacy/tests/pipeline/test_entity_ruler.py
index f2031d0a9..417f930cb 100644
--- a/spacy/tests/pipeline/test_entity_ruler.py
+++ b/spacy/tests/pipeline/test_entity_ruler.py
@@ -5,12 +5,15 @@ from spacy.tokens import Doc, Span
from spacy.language import Language
from spacy.lang.en import English
from spacy.pipeline import EntityRuler, EntityRecognizer, merge_entities
+from spacy.pipeline import SpanRuler
from spacy.pipeline.ner import DEFAULT_NER_MODEL
from spacy.errors import MatchPatternError
from spacy.tests.util import make_tempdir
from thinc.api import NumpyOps, get_current_ops
+ENTITY_RULERS = ["entity_ruler", "future_entity_ruler"]
+
@pytest.fixture
def nlp():
@@ -37,12 +40,14 @@ def add_ent_component(doc):
@pytest.mark.issue(3345)
-def test_issue3345():
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_issue3345(entity_ruler_factory):
"""Test case where preset entity crosses sentence boundary."""
nlp = English()
doc = Doc(nlp.vocab, words=["I", "live", "in", "New", "York"])
doc[4].is_sent_start = True
- ruler = EntityRuler(nlp, patterns=[{"label": "GPE", "pattern": "New York"}])
+ ruler = nlp.add_pipe(entity_ruler_factory, name="entity_ruler")
+ ruler.add_patterns([{"label": "GPE", "pattern": "New York"}])
cfg = {"model": DEFAULT_NER_MODEL}
model = registry.resolve(cfg, validate=True)["model"]
ner = EntityRecognizer(doc.vocab, model)
@@ -60,13 +65,18 @@ def test_issue3345():
@pytest.mark.issue(4849)
-def test_issue4849():
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_issue4849(entity_ruler_factory):
nlp = English()
patterns = [
{"label": "PERSON", "pattern": "joe biden", "id": "joe-biden"},
{"label": "PERSON", "pattern": "bernie sanders", "id": "bernie-sanders"},
]
- ruler = nlp.add_pipe("entity_ruler", config={"phrase_matcher_attr": "LOWER"})
+ ruler = nlp.add_pipe(
+ entity_ruler_factory,
+ name="entity_ruler",
+ config={"phrase_matcher_attr": "LOWER"},
+ )
ruler.add_patterns(patterns)
text = """
The left is starting to take aim at Democratic front-runner Joe Biden.
@@ -86,10 +96,11 @@ def test_issue4849():
@pytest.mark.issue(5918)
-def test_issue5918():
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_issue5918(entity_ruler_factory):
# Test edge case when merging entities.
nlp = English()
- ruler = nlp.add_pipe("entity_ruler")
+ ruler = nlp.add_pipe(entity_ruler_factory, name="entity_ruler")
patterns = [
{"label": "ORG", "pattern": "Digicon Inc"},
{"label": "ORG", "pattern": "Rotan Mosle Inc's"},
@@ -114,9 +125,10 @@ def test_issue5918():
@pytest.mark.issue(8168)
-def test_issue8168():
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_issue8168(entity_ruler_factory):
nlp = English()
- ruler = nlp.add_pipe("entity_ruler")
+ ruler = nlp.add_pipe(entity_ruler_factory, name="entity_ruler")
patterns = [
{"label": "ORG", "pattern": "Apple"},
{
@@ -131,14 +143,17 @@ def test_issue8168():
},
]
ruler.add_patterns(patterns)
-
- assert ruler._ent_ids == {8043148519967183733: ("GPE", "san-francisco")}
+ doc = nlp("San Francisco San Fran")
+ assert all(t.ent_id_ == "san-francisco" for t in doc)
@pytest.mark.issue(8216)
-def test_entity_ruler_fix8216(nlp, patterns):
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_fix8216(nlp, patterns, entity_ruler_factory):
"""Test that patterns don't get added excessively."""
- ruler = nlp.add_pipe("entity_ruler", config={"validate": True})
+ ruler = nlp.add_pipe(
+ entity_ruler_factory, name="entity_ruler", config={"validate": True}
+ )
ruler.add_patterns(patterns)
pattern_count = sum(len(mm) for mm in ruler.matcher._patterns.values())
assert pattern_count > 0
@@ -147,13 +162,16 @@ def test_entity_ruler_fix8216(nlp, patterns):
assert after_count == pattern_count
-def test_entity_ruler_init(nlp, patterns):
- ruler = EntityRuler(nlp, patterns=patterns)
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_init(nlp, patterns, entity_ruler_factory):
+ ruler = nlp.add_pipe(entity_ruler_factory, name="entity_ruler")
+ ruler.add_patterns(patterns)
assert len(ruler) == len(patterns)
assert len(ruler.labels) == 4
assert "HELLO" in ruler
assert "BYE" in ruler
- ruler = nlp.add_pipe("entity_ruler")
+ nlp.remove_pipe("entity_ruler")
+ ruler = nlp.add_pipe(entity_ruler_factory, name="entity_ruler")
ruler.add_patterns(patterns)
doc = nlp("hello world bye bye")
assert len(doc.ents) == 2
@@ -161,20 +179,23 @@ def test_entity_ruler_init(nlp, patterns):
assert doc.ents[1].label_ == "BYE"
-def test_entity_ruler_no_patterns_warns(nlp):
- ruler = EntityRuler(nlp)
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_no_patterns_warns(nlp, entity_ruler_factory):
+ ruler = nlp.add_pipe(entity_ruler_factory, name="entity_ruler")
assert len(ruler) == 0
assert len(ruler.labels) == 0
- nlp.add_pipe("entity_ruler")
+ nlp.remove_pipe("entity_ruler")
+ nlp.add_pipe(entity_ruler_factory, name="entity_ruler")
assert nlp.pipe_names == ["entity_ruler"]
with pytest.warns(UserWarning):
doc = nlp("hello world bye bye")
assert len(doc.ents) == 0
-def test_entity_ruler_init_patterns(nlp, patterns):
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_init_patterns(nlp, patterns, entity_ruler_factory):
# initialize with patterns
- ruler = nlp.add_pipe("entity_ruler")
+ ruler = nlp.add_pipe(entity_ruler_factory, name="entity_ruler")
assert len(ruler.labels) == 0
ruler.initialize(lambda: [], patterns=patterns)
assert len(ruler.labels) == 4
@@ -186,7 +207,7 @@ def test_entity_ruler_init_patterns(nlp, patterns):
nlp.config["initialize"]["components"]["entity_ruler"] = {
"patterns": {"@misc": "entity_ruler_patterns"}
}
- ruler = nlp.add_pipe("entity_ruler")
+ ruler = nlp.add_pipe(entity_ruler_factory, name="entity_ruler")
assert len(ruler.labels) == 0
nlp.initialize()
assert len(ruler.labels) == 4
@@ -195,18 +216,20 @@ def test_entity_ruler_init_patterns(nlp, patterns):
assert doc.ents[1].label_ == "BYE"
-def test_entity_ruler_init_clear(nlp, patterns):
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_init_clear(nlp, patterns, entity_ruler_factory):
"""Test that initialization clears patterns."""
- ruler = nlp.add_pipe("entity_ruler")
+ ruler = nlp.add_pipe(entity_ruler_factory, name="entity_ruler")
ruler.add_patterns(patterns)
assert len(ruler.labels) == 4
ruler.initialize(lambda: [])
assert len(ruler.labels) == 0
-def test_entity_ruler_clear(nlp, patterns):
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_clear(nlp, patterns, entity_ruler_factory):
"""Test that initialization clears patterns."""
- ruler = nlp.add_pipe("entity_ruler")
+ ruler = nlp.add_pipe(entity_ruler_factory, name="entity_ruler")
ruler.add_patterns(patterns)
assert len(ruler.labels) == 4
doc = nlp("hello world")
@@ -218,8 +241,9 @@ def test_entity_ruler_clear(nlp, patterns):
assert len(doc.ents) == 0
-def test_entity_ruler_existing(nlp, patterns):
- ruler = nlp.add_pipe("entity_ruler")
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_existing(nlp, patterns, entity_ruler_factory):
+ ruler = nlp.add_pipe(entity_ruler_factory, name="entity_ruler")
ruler.add_patterns(patterns)
nlp.add_pipe("add_ent", before="entity_ruler")
doc = nlp("OH HELLO WORLD bye bye")
@@ -228,8 +252,11 @@ def test_entity_ruler_existing(nlp, patterns):
assert doc.ents[1].label_ == "BYE"
-def test_entity_ruler_existing_overwrite(nlp, patterns):
- ruler = nlp.add_pipe("entity_ruler", config={"overwrite_ents": True})
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_existing_overwrite(nlp, patterns, entity_ruler_factory):
+ ruler = nlp.add_pipe(
+ entity_ruler_factory, name="entity_ruler", config={"overwrite_ents": True}
+ )
ruler.add_patterns(patterns)
nlp.add_pipe("add_ent", before="entity_ruler")
doc = nlp("OH HELLO WORLD bye bye")
@@ -239,8 +266,11 @@ def test_entity_ruler_existing_overwrite(nlp, patterns):
assert doc.ents[1].label_ == "BYE"
-def test_entity_ruler_existing_complex(nlp, patterns):
- ruler = nlp.add_pipe("entity_ruler", config={"overwrite_ents": True})
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_existing_complex(nlp, patterns, entity_ruler_factory):
+ ruler = nlp.add_pipe(
+ entity_ruler_factory, name="entity_ruler", config={"overwrite_ents": True}
+ )
ruler.add_patterns(patterns)
nlp.add_pipe("add_ent", before="entity_ruler")
doc = nlp("foo foo bye bye")
@@ -251,8 +281,11 @@ def test_entity_ruler_existing_complex(nlp, patterns):
assert len(doc.ents[1]) == 2
-def test_entity_ruler_entity_id(nlp, patterns):
- ruler = nlp.add_pipe("entity_ruler", config={"overwrite_ents": True})
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_entity_id(nlp, patterns, entity_ruler_factory):
+ ruler = nlp.add_pipe(
+ entity_ruler_factory, name="entity_ruler", config={"overwrite_ents": True}
+ )
ruler.add_patterns(patterns)
doc = nlp("Apple is a technology company")
assert len(doc.ents) == 1
@@ -260,18 +293,21 @@ def test_entity_ruler_entity_id(nlp, patterns):
assert doc.ents[0].ent_id_ == "a1"
-def test_entity_ruler_cfg_ent_id_sep(nlp, patterns):
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_cfg_ent_id_sep(nlp, patterns, entity_ruler_factory):
config = {"overwrite_ents": True, "ent_id_sep": "**"}
- ruler = nlp.add_pipe("entity_ruler", config=config)
+ ruler = nlp.add_pipe(entity_ruler_factory, name="entity_ruler", config=config)
ruler.add_patterns(patterns)
- assert "TECH_ORG**a1" in ruler.phrase_patterns
doc = nlp("Apple is a technology company")
+ if isinstance(ruler, EntityRuler):
+ assert "TECH_ORG**a1" in ruler.phrase_patterns
assert len(doc.ents) == 1
assert doc.ents[0].label_ == "TECH_ORG"
assert doc.ents[0].ent_id_ == "a1"
-def test_entity_ruler_serialize_bytes(nlp, patterns):
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_serialize_bytes(nlp, patterns, entity_ruler_factory):
ruler = EntityRuler(nlp, patterns=patterns)
assert len(ruler) == len(patterns)
assert len(ruler.labels) == 4
@@ -288,7 +324,10 @@ def test_entity_ruler_serialize_bytes(nlp, patterns):
assert sorted(new_ruler.labels) == sorted(ruler.labels)
-def test_entity_ruler_serialize_phrase_matcher_attr_bytes(nlp, patterns):
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_serialize_phrase_matcher_attr_bytes(
+ nlp, patterns, entity_ruler_factory
+):
ruler = EntityRuler(nlp, phrase_matcher_attr="LOWER", patterns=patterns)
assert len(ruler) == len(patterns)
assert len(ruler.labels) == 4
@@ -303,8 +342,9 @@ def test_entity_ruler_serialize_phrase_matcher_attr_bytes(nlp, patterns):
assert new_ruler.phrase_matcher_attr == "LOWER"
-def test_entity_ruler_validate(nlp):
- ruler = EntityRuler(nlp)
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_validate(nlp, entity_ruler_factory):
+ ruler = nlp.add_pipe(entity_ruler_factory, name="entity_ruler")
validated_ruler = EntityRuler(nlp, validate=True)
valid_pattern = {"label": "HELLO", "pattern": [{"LOWER": "HELLO"}]}
@@ -322,32 +362,72 @@ def test_entity_ruler_validate(nlp):
validated_ruler.add_patterns([invalid_pattern])
-def test_entity_ruler_properties(nlp, patterns):
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_properties(nlp, patterns, entity_ruler_factory):
ruler = EntityRuler(nlp, patterns=patterns, overwrite_ents=True)
assert sorted(ruler.labels) == sorted(["HELLO", "BYE", "COMPLEX", "TECH_ORG"])
assert sorted(ruler.ent_ids) == ["a1", "a2"]
-def test_entity_ruler_overlapping_spans(nlp):
- ruler = EntityRuler(nlp)
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_overlapping_spans(nlp, entity_ruler_factory):
+ ruler = nlp.add_pipe(entity_ruler_factory, name="entity_ruler")
patterns = [
{"label": "FOOBAR", "pattern": "foo bar"},
{"label": "BARBAZ", "pattern": "bar baz"},
]
ruler.add_patterns(patterns)
- doc = ruler(nlp.make_doc("foo bar baz"))
+ doc = nlp("foo bar baz")
assert len(doc.ents) == 1
assert doc.ents[0].label_ == "FOOBAR"
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_fuzzy_pipe(nlp, entity_ruler_factory):
+ ruler = nlp.add_pipe(entity_ruler_factory, name="entity_ruler")
+ patterns = [{"label": "HELLO", "pattern": [{"LOWER": {"FUZZY": "hello"}}]}]
+ ruler.add_patterns(patterns)
+ doc = nlp("helloo")
+ assert len(doc.ents) == 1
+ assert doc.ents[0].label_ == "HELLO"
+
+
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_fuzzy(nlp, entity_ruler_factory):
+ ruler = nlp.add_pipe(entity_ruler_factory, name="entity_ruler")
+ patterns = [{"label": "HELLO", "pattern": [{"LOWER": {"FUZZY": "hello"}}]}]
+ ruler.add_patterns(patterns)
+ doc = nlp("helloo")
+ assert len(doc.ents) == 1
+ assert doc.ents[0].label_ == "HELLO"
+
+
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_fuzzy_disabled(nlp, entity_ruler_factory):
+ @registry.misc("test_fuzzy_compare_disabled")
+ def make_test_fuzzy_compare_disabled():
+ return lambda x, y, z: False
+
+ ruler = nlp.add_pipe(
+ entity_ruler_factory,
+ name="entity_ruler",
+ config={"matcher_fuzzy_compare": {"@misc": "test_fuzzy_compare_disabled"}},
+ )
+ patterns = [{"label": "HELLO", "pattern": [{"LOWER": {"FUZZY": "hello"}}]}]
+ ruler.add_patterns(patterns)
+ doc = nlp("helloo")
+ assert len(doc.ents) == 0
+
+
@pytest.mark.parametrize("n_process", [1, 2])
-def test_entity_ruler_multiprocessing(nlp, n_process):
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_multiprocessing(nlp, n_process, entity_ruler_factory):
if isinstance(get_current_ops, NumpyOps) or n_process < 2:
texts = ["I enjoy eating Pizza Hut pizza."]
patterns = [{"label": "FASTFOOD", "pattern": "Pizza Hut", "id": "1234"}]
- ruler = nlp.add_pipe("entity_ruler")
+ ruler = nlp.add_pipe(entity_ruler_factory, name="entity_ruler")
ruler.add_patterns(patterns)
for doc in nlp.pipe(texts, n_process=2):
@@ -355,8 +435,9 @@ def test_entity_ruler_multiprocessing(nlp, n_process):
assert ent.ent_id_ == "1234"
-def test_entity_ruler_serialize_jsonl(nlp, patterns):
- ruler = nlp.add_pipe("entity_ruler")
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_serialize_jsonl(nlp, patterns, entity_ruler_factory):
+ ruler = nlp.add_pipe(entity_ruler_factory, name="entity_ruler")
ruler.add_patterns(patterns)
with make_tempdir() as d:
ruler.to_disk(d / "test_ruler.jsonl")
@@ -365,8 +446,9 @@ def test_entity_ruler_serialize_jsonl(nlp, patterns):
ruler.from_disk(d / "non_existing.jsonl") # read from a bad jsonl file
-def test_entity_ruler_serialize_dir(nlp, patterns):
- ruler = nlp.add_pipe("entity_ruler")
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_serialize_dir(nlp, patterns, entity_ruler_factory):
+ ruler = nlp.add_pipe(entity_ruler_factory, name="entity_ruler")
ruler.add_patterns(patterns)
with make_tempdir() as d:
ruler.to_disk(d / "test_ruler")
@@ -375,52 +457,65 @@ def test_entity_ruler_serialize_dir(nlp, patterns):
ruler.from_disk(d / "non_existing_dir") # read from a bad directory
-def test_entity_ruler_remove_basic(nlp):
- ruler = EntityRuler(nlp)
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_remove_basic(nlp, entity_ruler_factory):
+ ruler = nlp.add_pipe(entity_ruler_factory, name="entity_ruler")
patterns = [
- {"label": "PERSON", "pattern": "Duygu", "id": "duygu"},
+ {"label": "PERSON", "pattern": "Dina", "id": "dina"},
{"label": "ORG", "pattern": "ACME", "id": "acme"},
{"label": "ORG", "pattern": "ACM"},
]
ruler.add_patterns(patterns)
- doc = ruler(nlp.make_doc("Duygu went to school"))
+ doc = nlp("Dina went to school")
assert len(ruler.patterns) == 3
assert len(doc.ents) == 1
+ if isinstance(ruler, EntityRuler):
+ assert "PERSON||dina" in ruler.phrase_matcher
assert doc.ents[0].label_ == "PERSON"
- assert doc.ents[0].text == "Duygu"
- assert "PERSON||duygu" in ruler.phrase_matcher
- ruler.remove("duygu")
- doc = ruler(nlp.make_doc("Duygu went to school"))
+ assert doc.ents[0].text == "Dina"
+ if isinstance(ruler, EntityRuler):
+ ruler.remove("dina")
+ else:
+ ruler.remove_by_id("dina")
+ doc = nlp("Dina went to school")
assert len(doc.ents) == 0
- assert "PERSON||duygu" not in ruler.phrase_matcher
+ if isinstance(ruler, EntityRuler):
+ assert "PERSON||dina" not in ruler.phrase_matcher
assert len(ruler.patterns) == 2
-def test_entity_ruler_remove_same_id_multiple_patterns(nlp):
- ruler = EntityRuler(nlp)
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_remove_same_id_multiple_patterns(nlp, entity_ruler_factory):
+ ruler = nlp.add_pipe(entity_ruler_factory, name="entity_ruler")
patterns = [
- {"label": "PERSON", "pattern": "Duygu", "id": "duygu"},
- {"label": "ORG", "pattern": "DuyguCorp", "id": "duygu"},
+ {"label": "PERSON", "pattern": "Dina", "id": "dina"},
+ {"label": "ORG", "pattern": "DinaCorp", "id": "dina"},
{"label": "ORG", "pattern": "ACME", "id": "acme"},
]
ruler.add_patterns(patterns)
- doc = ruler(nlp.make_doc("Duygu founded DuyguCorp and ACME."))
+ doc = nlp("Dina founded DinaCorp and ACME.")
assert len(ruler.patterns) == 3
- assert "PERSON||duygu" in ruler.phrase_matcher
- assert "ORG||duygu" in ruler.phrase_matcher
+ if isinstance(ruler, EntityRuler):
+ assert "PERSON||dina" in ruler.phrase_matcher
+ assert "ORG||dina" in ruler.phrase_matcher
assert len(doc.ents) == 3
- ruler.remove("duygu")
- doc = ruler(nlp.make_doc("Duygu founded DuyguCorp and ACME."))
+ if isinstance(ruler, EntityRuler):
+ ruler.remove("dina")
+ else:
+ ruler.remove_by_id("dina")
+ doc = nlp("Dina founded DinaCorp and ACME.")
assert len(ruler.patterns) == 1
- assert "PERSON||duygu" not in ruler.phrase_matcher
- assert "ORG||duygu" not in ruler.phrase_matcher
+ if isinstance(ruler, EntityRuler):
+ assert "PERSON||dina" not in ruler.phrase_matcher
+ assert "ORG||dina" not in ruler.phrase_matcher
assert len(doc.ents) == 1
-def test_entity_ruler_remove_nonexisting_pattern(nlp):
- ruler = EntityRuler(nlp)
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_remove_nonexisting_pattern(nlp, entity_ruler_factory):
+ ruler = nlp.add_pipe(entity_ruler_factory, name="entity_ruler")
patterns = [
- {"label": "PERSON", "pattern": "Duygu", "id": "duygu"},
+ {"label": "PERSON", "pattern": "Dina", "id": "dina"},
{"label": "ORG", "pattern": "ACME", "id": "acme"},
{"label": "ORG", "pattern": "ACM"},
]
@@ -428,82 +523,108 @@ def test_entity_ruler_remove_nonexisting_pattern(nlp):
assert len(ruler.patterns) == 3
with pytest.raises(ValueError):
ruler.remove("nepattern")
- assert len(ruler.patterns) == 3
+ if isinstance(ruler, SpanRuler):
+ with pytest.raises(ValueError):
+ ruler.remove_by_id("nepattern")
-def test_entity_ruler_remove_several_patterns(nlp):
- ruler = EntityRuler(nlp)
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_remove_several_patterns(nlp, entity_ruler_factory):
+ ruler = nlp.add_pipe(entity_ruler_factory, name="entity_ruler")
patterns = [
- {"label": "PERSON", "pattern": "Duygu", "id": "duygu"},
+ {"label": "PERSON", "pattern": "Dina", "id": "dina"},
{"label": "ORG", "pattern": "ACME", "id": "acme"},
{"label": "ORG", "pattern": "ACM"},
]
ruler.add_patterns(patterns)
- doc = ruler(nlp.make_doc("Duygu founded her company ACME."))
+ doc = nlp("Dina founded her company ACME.")
assert len(ruler.patterns) == 3
assert len(doc.ents) == 2
assert doc.ents[0].label_ == "PERSON"
- assert doc.ents[0].text == "Duygu"
+ assert doc.ents[0].text == "Dina"
assert doc.ents[1].label_ == "ORG"
assert doc.ents[1].text == "ACME"
- ruler.remove("duygu")
- doc = ruler(nlp.make_doc("Duygu founded her company ACME"))
+ if isinstance(ruler, EntityRuler):
+ ruler.remove("dina")
+ else:
+ ruler.remove_by_id("dina")
+ doc = nlp("Dina founded her company ACME")
assert len(ruler.patterns) == 2
assert len(doc.ents) == 1
assert doc.ents[0].label_ == "ORG"
assert doc.ents[0].text == "ACME"
- ruler.remove("acme")
- doc = ruler(nlp.make_doc("Duygu founded her company ACME"))
+ if isinstance(ruler, EntityRuler):
+ ruler.remove("acme")
+ else:
+ ruler.remove_by_id("acme")
+ doc = nlp("Dina founded her company ACME")
assert len(ruler.patterns) == 1
assert len(doc.ents) == 0
-def test_entity_ruler_remove_patterns_in_a_row(nlp):
- ruler = EntityRuler(nlp)
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_remove_patterns_in_a_row(nlp, entity_ruler_factory):
+ ruler = nlp.add_pipe(entity_ruler_factory, name="entity_ruler")
patterns = [
- {"label": "PERSON", "pattern": "Duygu", "id": "duygu"},
+ {"label": "PERSON", "pattern": "Dina", "id": "dina"},
{"label": "ORG", "pattern": "ACME", "id": "acme"},
{"label": "DATE", "pattern": "her birthday", "id": "bday"},
{"label": "ORG", "pattern": "ACM"},
]
ruler.add_patterns(patterns)
- doc = ruler(nlp.make_doc("Duygu founded her company ACME on her birthday"))
+ doc = nlp("Dina founded her company ACME on her birthday")
assert len(doc.ents) == 3
assert doc.ents[0].label_ == "PERSON"
- assert doc.ents[0].text == "Duygu"
+ assert doc.ents[0].text == "Dina"
assert doc.ents[1].label_ == "ORG"
assert doc.ents[1].text == "ACME"
assert doc.ents[2].label_ == "DATE"
assert doc.ents[2].text == "her birthday"
- ruler.remove("duygu")
- ruler.remove("acme")
- ruler.remove("bday")
- doc = ruler(nlp.make_doc("Duygu went to school"))
+ if isinstance(ruler, EntityRuler):
+ ruler.remove("dina")
+ ruler.remove("acme")
+ ruler.remove("bday")
+ else:
+ ruler.remove_by_id("dina")
+ ruler.remove_by_id("acme")
+ ruler.remove_by_id("bday")
+ doc = nlp("Dina went to school")
assert len(doc.ents) == 0
-def test_entity_ruler_remove_all_patterns(nlp):
- ruler = EntityRuler(nlp)
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_remove_all_patterns(nlp, entity_ruler_factory):
+ ruler = nlp.add_pipe(entity_ruler_factory, name="entity_ruler")
patterns = [
- {"label": "PERSON", "pattern": "Duygu", "id": "duygu"},
+ {"label": "PERSON", "pattern": "Dina", "id": "dina"},
{"label": "ORG", "pattern": "ACME", "id": "acme"},
{"label": "DATE", "pattern": "her birthday", "id": "bday"},
]
ruler.add_patterns(patterns)
assert len(ruler.patterns) == 3
- ruler.remove("duygu")
+ if isinstance(ruler, EntityRuler):
+ ruler.remove("dina")
+ else:
+ ruler.remove_by_id("dina")
assert len(ruler.patterns) == 2
- ruler.remove("acme")
+ if isinstance(ruler, EntityRuler):
+ ruler.remove("acme")
+ else:
+ ruler.remove_by_id("acme")
assert len(ruler.patterns) == 1
- ruler.remove("bday")
+ if isinstance(ruler, EntityRuler):
+ ruler.remove("bday")
+ else:
+ ruler.remove_by_id("bday")
assert len(ruler.patterns) == 0
with pytest.warns(UserWarning):
- doc = ruler(nlp.make_doc("Duygu founded her company ACME on her birthday"))
+ doc = nlp("Dina founded her company ACME on her birthday")
assert len(doc.ents) == 0
-def test_entity_ruler_remove_and_add(nlp):
- ruler = EntityRuler(nlp)
+@pytest.mark.parametrize("entity_ruler_factory", ENTITY_RULERS)
+def test_entity_ruler_remove_and_add(nlp, entity_ruler_factory):
+ ruler = nlp.add_pipe(entity_ruler_factory, name="entity_ruler")
patterns = [{"label": "DATE", "pattern": "last time"}]
ruler.add_patterns(patterns)
doc = ruler(
@@ -524,7 +645,10 @@ def test_entity_ruler_remove_and_add(nlp):
assert doc.ents[0].text == "last time"
assert doc.ents[1].label_ == "DATE"
assert doc.ents[1].text == "this time"
- ruler.remove("ttime")
+ if isinstance(ruler, EntityRuler):
+ ruler.remove("ttime")
+ else:
+ ruler.remove_by_id("ttime")
doc = ruler(
nlp.make_doc("I saw him last time we met, this time he brought some flowers")
)
@@ -547,7 +671,10 @@ def test_entity_ruler_remove_and_add(nlp):
)
assert len(ruler.patterns) == 3
assert len(doc.ents) == 3
- ruler.remove("ttime")
+ if isinstance(ruler, EntityRuler):
+ ruler.remove("ttime")
+ else:
+ ruler.remove_by_id("ttime")
doc = ruler(
nlp.make_doc(
"I saw him last time we met, this time he brought some flowers, another time some chocolate."
diff --git a/spacy/tests/pipeline/test_morphologizer.py b/spacy/tests/pipeline/test_morphologizer.py
index 11d6f0477..33696bfd8 100644
--- a/spacy/tests/pipeline/test_morphologizer.py
+++ b/spacy/tests/pipeline/test_morphologizer.py
@@ -184,7 +184,7 @@ def test_overfitting_IO():
token.pos_ = ""
token.set_morph(None)
optimizer = nlp.initialize(get_examples=lambda: train_examples)
- print(nlp.get_pipe("morphologizer").labels)
+ assert nlp.get_pipe("morphologizer").labels is not None
for i in range(50):
losses = {}
nlp.update(train_examples, sgd=optimizer, losses=losses)
diff --git a/spacy/tests/pipeline/test_pipe_factories.py b/spacy/tests/pipeline/test_pipe_factories.py
index 4128e2a48..232b0512e 100644
--- a/spacy/tests/pipeline/test_pipe_factories.py
+++ b/spacy/tests/pipeline/test_pipe_factories.py
@@ -119,6 +119,7 @@ def test_pipe_class_component_config():
self.value1 = value1
self.value2 = value2
self.is_base = True
+ self.name = name
def __call__(self, doc: Doc) -> Doc:
return doc
@@ -141,12 +142,16 @@ def test_pipe_class_component_config():
nlp.add_pipe(name)
with pytest.raises(ConfigValidationError): # invalid config
nlp.add_pipe(name, config={"value1": "10", "value2": "hello"})
- nlp.add_pipe(name, config={"value1": 10, "value2": "hello"})
+ with pytest.warns(UserWarning):
+ nlp.add_pipe(
+ name, config={"value1": 10, "value2": "hello", "name": "wrong_name"}
+ )
pipe = nlp.get_pipe(name)
assert isinstance(pipe.nlp, Language)
assert pipe.value1 == 10
assert pipe.value2 == "hello"
assert pipe.is_base is True
+ assert pipe.name == name
nlp_en = English()
with pytest.raises(ConfigValidationError): # invalid config
diff --git a/spacy/tests/pipeline/test_pipe_methods.py b/spacy/tests/pipeline/test_pipe_methods.py
index 4b8fb8ebc..4dd7bae16 100644
--- a/spacy/tests/pipeline/test_pipe_methods.py
+++ b/spacy/tests/pipeline/test_pipe_methods.py
@@ -4,13 +4,14 @@ import numpy
import pytest
from thinc.api import get_current_ops
+import spacy
from spacy.lang.en import English
from spacy.lang.en.syntax_iterators import noun_chunks
from spacy.language import Language
from spacy.pipeline import TrainablePipe
from spacy.tokens import Doc
from spacy.training import Example
-from spacy.util import SimpleFrozenList, get_arg_names
+from spacy.util import SimpleFrozenList, get_arg_names, make_tempdir
from spacy.vocab import Vocab
@@ -602,3 +603,86 @@ def test_update_with_annotates():
assert results[component] == "".join(eg.predicted.text for eg in examples)
for component in components - set(components_to_annotate):
assert results[component] == ""
+
+
+@pytest.mark.issue(11443)
+def test_enable_disable_conflict_with_config():
+ """Test conflict between enable/disable w.r.t. `nlp.disabled` set in the config."""
+ nlp = English()
+ nlp.add_pipe("tagger")
+ nlp.add_pipe("senter")
+ nlp.add_pipe("sentencizer")
+
+ with make_tempdir() as tmp_dir:
+ nlp.to_disk(tmp_dir)
+ # Expected to succeed, as config and arguments do not conflict.
+ assert spacy.load(
+ tmp_dir, enable=["tagger"], config={"nlp": {"disabled": ["senter"]}}
+ ).disabled == ["senter", "sentencizer"]
+ # Expected to succeed without warning due to the lack of a conflicting config option.
+ spacy.load(tmp_dir, enable=["tagger"])
+ # Expected to fail due to conflict between enable and disabled.
+ with pytest.raises(ValueError):
+ spacy.load(
+ tmp_dir,
+ enable=["senter"],
+ config={"nlp": {"disabled": ["senter", "tagger"]}},
+ )
+
+
+def test_load_disable_enable():
+ """Tests spacy.load() with dis-/enabling components."""
+
+ base_nlp = English()
+ for pipe in ("sentencizer", "tagger", "parser"):
+ base_nlp.add_pipe(pipe)
+
+ with make_tempdir() as tmp_dir:
+ base_nlp.to_disk(tmp_dir)
+ to_disable = ["parser", "tagger"]
+ to_enable = ["tagger", "parser"]
+ single_str = "tagger"
+
+ # Setting only `disable`.
+ nlp = spacy.load(tmp_dir, disable=to_disable)
+ assert all([comp_name in nlp.disabled for comp_name in to_disable])
+
+ # Setting only `enable`.
+ nlp = spacy.load(tmp_dir, enable=to_enable)
+ assert all(
+ [
+ (comp_name in nlp.disabled) is (comp_name not in to_enable)
+ for comp_name in nlp.component_names
+ ]
+ )
+
+ # Loading with a string representing one component
+ nlp = spacy.load(tmp_dir, exclude=single_str)
+ assert single_str not in nlp.component_names
+
+ nlp = spacy.load(tmp_dir, disable=single_str)
+ assert single_str in nlp.component_names
+ assert single_str not in nlp.pipe_names
+ assert nlp._disabled == {single_str}
+ assert nlp.disabled == [single_str]
+
+ # Testing consistent enable/disable combination.
+ nlp = spacy.load(
+ tmp_dir,
+ enable=to_enable,
+ disable=[
+ comp_name
+ for comp_name in nlp.component_names
+ if comp_name not in to_enable
+ ],
+ )
+ assert all(
+ [
+ (comp_name in nlp.disabled) is (comp_name not in to_enable)
+ for comp_name in nlp.component_names
+ ]
+ )
+
+ # Inconsistent enable/disable combination.
+ with pytest.raises(ValueError):
+ spacy.load(tmp_dir, enable=to_enable, disable=["parser"])
diff --git a/spacy/tests/pipeline/test_span_ruler.py b/spacy/tests/pipeline/test_span_ruler.py
new file mode 100644
index 000000000..794815359
--- /dev/null
+++ b/spacy/tests/pipeline/test_span_ruler.py
@@ -0,0 +1,465 @@
+import pytest
+
+import spacy
+from spacy import registry
+from spacy.errors import MatchPatternError
+from spacy.tokens import Span
+from spacy.training import Example
+from spacy.tests.util import make_tempdir
+
+from thinc.api import NumpyOps, get_current_ops
+
+
+@pytest.fixture
+@registry.misc("span_ruler_patterns")
+def patterns():
+ return [
+ {"label": "HELLO", "pattern": "hello world", "id": "hello1"},
+ {"label": "BYE", "pattern": [{"LOWER": "bye"}, {"LOWER": "bye"}]},
+ {"label": "HELLO", "pattern": [{"ORTH": "HELLO"}], "id": "hello2"},
+ {"label": "COMPLEX", "pattern": [{"ORTH": "foo", "OP": "*"}]},
+ {"label": "TECH_ORG", "pattern": "Apple"},
+ {"label": "TECH_ORG", "pattern": "Microsoft"},
+ ]
+
+
+@pytest.fixture
+def overlapping_patterns():
+ return [
+ {"label": "FOOBAR", "pattern": "foo bar"},
+ {"label": "BARBAZ", "pattern": "bar baz"},
+ ]
+
+
+@pytest.fixture
+def person_org_patterns():
+ return [
+ {"label": "PERSON", "pattern": "Dina"},
+ {"label": "ORG", "pattern": "ACME"},
+ {"label": "ORG", "pattern": "ACM"},
+ ]
+
+
+@pytest.fixture
+def person_org_date_patterns(person_org_patterns):
+ return person_org_patterns + [{"label": "DATE", "pattern": "June 14th"}]
+
+
+def test_span_ruler_add_empty(patterns):
+ """Test that patterns don't get added excessively."""
+ nlp = spacy.blank("xx")
+ ruler = nlp.add_pipe("span_ruler", config={"validate": True})
+ ruler.add_patterns(patterns)
+ pattern_count = sum(len(mm) for mm in ruler.matcher._patterns.values())
+ assert pattern_count > 0
+ ruler.add_patterns([])
+ after_count = sum(len(mm) for mm in ruler.matcher._patterns.values())
+ assert after_count == pattern_count
+
+
+def test_span_ruler_init(patterns):
+ nlp = spacy.blank("xx")
+ ruler = nlp.add_pipe("span_ruler")
+ ruler.add_patterns(patterns)
+ assert len(ruler) == len(patterns)
+ assert len(ruler.labels) == 4
+ assert "HELLO" in ruler
+ assert "BYE" in ruler
+ doc = nlp("hello world bye bye")
+ assert len(doc.spans["ruler"]) == 2
+ assert doc.spans["ruler"][0].label_ == "HELLO"
+ assert doc.spans["ruler"][0].id_ == "hello1"
+ assert doc.spans["ruler"][1].label_ == "BYE"
+ assert doc.spans["ruler"][1].id_ == ""
+
+
+def test_span_ruler_no_patterns_warns():
+ nlp = spacy.blank("xx")
+ ruler = nlp.add_pipe("span_ruler")
+ assert len(ruler) == 0
+ assert len(ruler.labels) == 0
+ assert nlp.pipe_names == ["span_ruler"]
+ with pytest.warns(UserWarning):
+ doc = nlp("hello world bye bye")
+ assert len(doc.spans["ruler"]) == 0
+
+
+def test_span_ruler_init_patterns(patterns):
+ # initialize with patterns
+ nlp = spacy.blank("xx")
+ ruler = nlp.add_pipe("span_ruler")
+ assert len(ruler.labels) == 0
+ ruler.initialize(lambda: [], patterns=patterns)
+ assert len(ruler.labels) == 4
+ doc = nlp("hello world bye bye")
+ assert doc.spans["ruler"][0].label_ == "HELLO"
+ assert doc.spans["ruler"][1].label_ == "BYE"
+ nlp.remove_pipe("span_ruler")
+ # initialize with patterns from misc registry
+ nlp.config["initialize"]["components"]["span_ruler"] = {
+ "patterns": {"@misc": "span_ruler_patterns"}
+ }
+ ruler = nlp.add_pipe("span_ruler")
+ assert len(ruler.labels) == 0
+ nlp.initialize()
+ assert len(ruler.labels) == 4
+ doc = nlp("hello world bye bye")
+ assert doc.spans["ruler"][0].label_ == "HELLO"
+ assert doc.spans["ruler"][1].label_ == "BYE"
+
+
+def test_span_ruler_init_clear(patterns):
+ """Test that initialization clears patterns."""
+ nlp = spacy.blank("xx")
+ ruler = nlp.add_pipe("span_ruler")
+ ruler.add_patterns(patterns)
+ assert len(ruler.labels) == 4
+ ruler.initialize(lambda: [])
+ assert len(ruler.labels) == 0
+
+
+def test_span_ruler_clear(patterns):
+ nlp = spacy.blank("xx")
+ ruler = nlp.add_pipe("span_ruler")
+ ruler.add_patterns(patterns)
+ assert len(ruler.labels) == 4
+ doc = nlp("hello world")
+ assert len(doc.spans["ruler"]) == 1
+ ruler.clear()
+ assert len(ruler.labels) == 0
+ with pytest.warns(UserWarning):
+ doc = nlp("hello world")
+ assert len(doc.spans["ruler"]) == 0
+
+
+def test_span_ruler_existing(patterns):
+ nlp = spacy.blank("xx")
+ ruler = nlp.add_pipe("span_ruler", config={"overwrite": False})
+ ruler.add_patterns(patterns)
+ doc = nlp.make_doc("OH HELLO WORLD bye bye")
+ doc.spans["ruler"] = [doc[0:2]]
+ doc = nlp(doc)
+ assert len(doc.spans["ruler"]) == 3
+ assert doc.spans["ruler"][0] == doc[0:2]
+ assert doc.spans["ruler"][1].label_ == "HELLO"
+ assert doc.spans["ruler"][1].id_ == "hello2"
+ assert doc.spans["ruler"][2].label_ == "BYE"
+ assert doc.spans["ruler"][2].id_ == ""
+
+
+def test_span_ruler_existing_overwrite(patterns):
+ nlp = spacy.blank("xx")
+ ruler = nlp.add_pipe("span_ruler", config={"overwrite": True})
+ ruler.add_patterns(patterns)
+ doc = nlp.make_doc("OH HELLO WORLD bye bye")
+ doc.spans["ruler"] = [doc[0:2]]
+ doc = nlp(doc)
+ assert len(doc.spans["ruler"]) == 2
+ assert doc.spans["ruler"][0].label_ == "HELLO"
+ assert doc.spans["ruler"][0].text == "HELLO"
+ assert doc.spans["ruler"][1].label_ == "BYE"
+
+
+def test_span_ruler_serialize_bytes(patterns):
+ nlp = spacy.blank("xx")
+ ruler = nlp.add_pipe("span_ruler")
+ ruler.add_patterns(patterns)
+ assert len(ruler) == len(patterns)
+ assert len(ruler.labels) == 4
+ ruler_bytes = ruler.to_bytes()
+ new_nlp = spacy.blank("xx")
+ new_ruler = new_nlp.add_pipe("span_ruler")
+ assert len(new_ruler) == 0
+ assert len(new_ruler.labels) == 0
+ new_ruler = new_ruler.from_bytes(ruler_bytes)
+ assert len(new_ruler) == len(patterns)
+ assert len(new_ruler.labels) == 4
+ assert len(new_ruler.patterns) == len(ruler.patterns)
+ for pattern in ruler.patterns:
+ assert pattern in new_ruler.patterns
+ assert sorted(new_ruler.labels) == sorted(ruler.labels)
+
+
+def test_span_ruler_validate():
+ nlp = spacy.blank("xx")
+ ruler = nlp.add_pipe("span_ruler")
+ validated_ruler = nlp.add_pipe(
+ "span_ruler", name="validated_span_ruler", config={"validate": True}
+ )
+
+ valid_pattern = {"label": "HELLO", "pattern": [{"LOWER": "HELLO"}]}
+ invalid_pattern = {"label": "HELLO", "pattern": [{"ASDF": "HELLO"}]}
+
+ # invalid pattern raises error without validate
+ with pytest.raises(ValueError):
+ ruler.add_patterns([invalid_pattern])
+
+ # valid pattern is added without errors with validate
+ validated_ruler.add_patterns([valid_pattern])
+
+ # invalid pattern raises error with validate
+ with pytest.raises(MatchPatternError):
+ validated_ruler.add_patterns([invalid_pattern])
+
+
+def test_span_ruler_properties(patterns):
+ nlp = spacy.blank("xx")
+ ruler = nlp.add_pipe("span_ruler", config={"overwrite": True})
+ ruler.add_patterns(patterns)
+ assert sorted(ruler.labels) == sorted(set([p["label"] for p in patterns]))
+
+
+def test_span_ruler_overlapping_spans(overlapping_patterns):
+ nlp = spacy.blank("xx")
+ ruler = nlp.add_pipe("span_ruler")
+ ruler.add_patterns(overlapping_patterns)
+ doc = ruler(nlp.make_doc("foo bar baz"))
+ assert len(doc.spans["ruler"]) == 2
+ assert doc.spans["ruler"][0].label_ == "FOOBAR"
+ assert doc.spans["ruler"][1].label_ == "BARBAZ"
+
+
+def test_span_ruler_scorer(overlapping_patterns):
+ nlp = spacy.blank("xx")
+ ruler = nlp.add_pipe("span_ruler")
+ ruler.add_patterns(overlapping_patterns)
+ text = "foo bar baz"
+ pred_doc = ruler(nlp.make_doc(text))
+ assert len(pred_doc.spans["ruler"]) == 2
+ assert pred_doc.spans["ruler"][0].label_ == "FOOBAR"
+ assert pred_doc.spans["ruler"][1].label_ == "BARBAZ"
+
+ ref_doc = nlp.make_doc(text)
+ ref_doc.spans["ruler"] = [Span(ref_doc, 0, 2, label="FOOBAR")]
+ scores = nlp.evaluate([Example(pred_doc, ref_doc)])
+ assert scores["spans_ruler_p"] == 0.5
+ assert scores["spans_ruler_r"] == 1.0
+
+
+@pytest.mark.parametrize("n_process", [1, 2])
+def test_span_ruler_multiprocessing(n_process):
+ if isinstance(get_current_ops, NumpyOps) or n_process < 2:
+ texts = ["I enjoy eating Pizza Hut pizza."]
+
+ patterns = [{"label": "FASTFOOD", "pattern": "Pizza Hut"}]
+
+ nlp = spacy.blank("xx")
+ ruler = nlp.add_pipe("span_ruler")
+ ruler.add_patterns(patterns)
+
+ for doc in nlp.pipe(texts, n_process=2):
+ for ent in doc.spans["ruler"]:
+ assert ent.label_ == "FASTFOOD"
+
+
+def test_span_ruler_serialize_dir(patterns):
+ nlp = spacy.blank("xx")
+ ruler = nlp.add_pipe("span_ruler")
+ ruler.add_patterns(patterns)
+ with make_tempdir() as d:
+ ruler.to_disk(d / "test_ruler")
+ ruler.from_disk(d / "test_ruler") # read from an existing directory
+ with pytest.raises(ValueError):
+ ruler.from_disk(d / "non_existing_dir") # read from a bad directory
+
+
+def test_span_ruler_remove_basic(person_org_patterns):
+ nlp = spacy.blank("xx")
+ ruler = nlp.add_pipe("span_ruler")
+ ruler.add_patterns(person_org_patterns)
+ doc = ruler(nlp.make_doc("Dina went to school"))
+ assert len(ruler.patterns) == 3
+ assert len(doc.spans["ruler"]) == 1
+ assert doc.spans["ruler"][0].label_ == "PERSON"
+ assert doc.spans["ruler"][0].text == "Dina"
+ ruler.remove("PERSON")
+ doc = ruler(nlp.make_doc("Dina went to school"))
+ assert len(doc.spans["ruler"]) == 0
+ assert len(ruler.patterns) == 2
+
+
+def test_span_ruler_remove_nonexisting_pattern(person_org_patterns):
+ nlp = spacy.blank("xx")
+ ruler = nlp.add_pipe("span_ruler")
+ ruler.add_patterns(person_org_patterns)
+ assert len(ruler.patterns) == 3
+ with pytest.raises(ValueError):
+ ruler.remove("NE")
+ with pytest.raises(ValueError):
+ ruler.remove_by_id("NE")
+
+
+def test_span_ruler_remove_several_patterns(person_org_patterns):
+ nlp = spacy.blank("xx")
+ ruler = nlp.add_pipe("span_ruler")
+ ruler.add_patterns(person_org_patterns)
+ doc = ruler(nlp.make_doc("Dina founded the company ACME."))
+ assert len(ruler.patterns) == 3
+ assert len(doc.spans["ruler"]) == 2
+ assert doc.spans["ruler"][0].label_ == "PERSON"
+ assert doc.spans["ruler"][0].text == "Dina"
+ assert doc.spans["ruler"][1].label_ == "ORG"
+ assert doc.spans["ruler"][1].text == "ACME"
+ ruler.remove("PERSON")
+ doc = ruler(nlp.make_doc("Dina founded the company ACME"))
+ assert len(ruler.patterns) == 2
+ assert len(doc.spans["ruler"]) == 1
+ assert doc.spans["ruler"][0].label_ == "ORG"
+ assert doc.spans["ruler"][0].text == "ACME"
+ ruler.remove("ORG")
+ with pytest.warns(UserWarning):
+ doc = ruler(nlp.make_doc("Dina founded the company ACME"))
+ assert len(ruler.patterns) == 0
+ assert len(doc.spans["ruler"]) == 0
+
+
+def test_span_ruler_remove_patterns_in_a_row(person_org_date_patterns):
+ nlp = spacy.blank("xx")
+ ruler = nlp.add_pipe("span_ruler")
+ ruler.add_patterns(person_org_date_patterns)
+ doc = ruler(nlp.make_doc("Dina founded the company ACME on June 14th"))
+ assert len(doc.spans["ruler"]) == 3
+ assert doc.spans["ruler"][0].label_ == "PERSON"
+ assert doc.spans["ruler"][0].text == "Dina"
+ assert doc.spans["ruler"][1].label_ == "ORG"
+ assert doc.spans["ruler"][1].text == "ACME"
+ assert doc.spans["ruler"][2].label_ == "DATE"
+ assert doc.spans["ruler"][2].text == "June 14th"
+ ruler.remove("ORG")
+ ruler.remove("DATE")
+ doc = ruler(nlp.make_doc("Dina went to school"))
+ assert len(doc.spans["ruler"]) == 1
+
+
+def test_span_ruler_remove_all_patterns(person_org_date_patterns):
+ nlp = spacy.blank("xx")
+ ruler = nlp.add_pipe("span_ruler")
+ ruler.add_patterns(person_org_date_patterns)
+ assert len(ruler.patterns) == 4
+ ruler.remove("PERSON")
+ assert len(ruler.patterns) == 3
+ ruler.remove("ORG")
+ assert len(ruler.patterns) == 1
+ ruler.remove("DATE")
+ assert len(ruler.patterns) == 0
+ with pytest.warns(UserWarning):
+ doc = ruler(nlp.make_doc("Dina founded the company ACME on June 14th"))
+ assert len(doc.spans["ruler"]) == 0
+
+
+def test_span_ruler_remove_and_add():
+ nlp = spacy.blank("xx")
+ ruler = nlp.add_pipe("span_ruler")
+ patterns1 = [{"label": "DATE1", "pattern": "last time"}]
+ ruler.add_patterns(patterns1)
+ doc = ruler(
+ nlp.make_doc("I saw him last time we met, this time he brought some flowers")
+ )
+ assert len(ruler.patterns) == 1
+ assert len(doc.spans["ruler"]) == 1
+ assert doc.spans["ruler"][0].label_ == "DATE1"
+ assert doc.spans["ruler"][0].text == "last time"
+ patterns2 = [{"label": "DATE2", "pattern": "this time"}]
+ ruler.add_patterns(patterns2)
+ doc = ruler(
+ nlp.make_doc("I saw him last time we met, this time he brought some flowers")
+ )
+ assert len(ruler.patterns) == 2
+ assert len(doc.spans["ruler"]) == 2
+ assert doc.spans["ruler"][0].label_ == "DATE1"
+ assert doc.spans["ruler"][0].text == "last time"
+ assert doc.spans["ruler"][1].label_ == "DATE2"
+ assert doc.spans["ruler"][1].text == "this time"
+ ruler.remove("DATE1")
+ doc = ruler(
+ nlp.make_doc("I saw him last time we met, this time he brought some flowers")
+ )
+ assert len(ruler.patterns) == 1
+ assert len(doc.spans["ruler"]) == 1
+ assert doc.spans["ruler"][0].label_ == "DATE2"
+ assert doc.spans["ruler"][0].text == "this time"
+ ruler.add_patterns(patterns1)
+ doc = ruler(
+ nlp.make_doc("I saw him last time we met, this time he brought some flowers")
+ )
+ assert len(ruler.patterns) == 2
+ assert len(doc.spans["ruler"]) == 2
+ patterns3 = [{"label": "DATE3", "pattern": "another time"}]
+ ruler.add_patterns(patterns3)
+ doc = ruler(
+ nlp.make_doc(
+ "I saw him last time we met, this time he brought some flowers, another time some chocolate."
+ )
+ )
+ assert len(ruler.patterns) == 3
+ assert len(doc.spans["ruler"]) == 3
+ ruler.remove("DATE3")
+ doc = ruler(
+ nlp.make_doc(
+ "I saw him last time we met, this time he brought some flowers, another time some chocolate."
+ )
+ )
+ assert len(ruler.patterns) == 2
+ assert len(doc.spans["ruler"]) == 2
+
+
+def test_span_ruler_spans_filter(overlapping_patterns):
+ nlp = spacy.blank("xx")
+ ruler = nlp.add_pipe(
+ "span_ruler",
+ config={"spans_filter": {"@misc": "spacy.first_longest_spans_filter.v1"}},
+ )
+ ruler.add_patterns(overlapping_patterns)
+ doc = ruler(nlp.make_doc("foo bar baz"))
+ assert len(doc.spans["ruler"]) == 1
+ assert doc.spans["ruler"][0].label_ == "FOOBAR"
+
+
+def test_span_ruler_ents_default_filter(overlapping_patterns):
+ nlp = spacy.blank("xx")
+ ruler = nlp.add_pipe("span_ruler", config={"annotate_ents": True})
+ ruler.add_patterns(overlapping_patterns)
+ doc = ruler(nlp.make_doc("foo bar baz"))
+ assert len(doc.ents) == 1
+ assert doc.ents[0].label_ == "FOOBAR"
+
+
+def test_span_ruler_ents_overwrite_filter(overlapping_patterns):
+ nlp = spacy.blank("xx")
+ ruler = nlp.add_pipe(
+ "span_ruler",
+ config={
+ "annotate_ents": True,
+ "overwrite": False,
+ "ents_filter": {"@misc": "spacy.prioritize_new_ents_filter.v1"},
+ },
+ )
+ ruler.add_patterns(overlapping_patterns)
+ # overlapping ents are clobbered, non-overlapping ents are preserved
+ doc = nlp.make_doc("foo bar baz a b c")
+ doc.ents = [Span(doc, 1, 3, label="BARBAZ"), Span(doc, 3, 6, label="ABC")]
+ doc = ruler(doc)
+ assert len(doc.ents) == 2
+ assert doc.ents[0].label_ == "FOOBAR"
+ assert doc.ents[1].label_ == "ABC"
+
+
+def test_span_ruler_ents_bad_filter(overlapping_patterns):
+ @registry.misc("test_pass_through_filter")
+ def make_pass_through_filter():
+ def pass_through_filter(spans1, spans2):
+ return spans1 + spans2
+
+ return pass_through_filter
+
+ nlp = spacy.blank("xx")
+ ruler = nlp.add_pipe(
+ "span_ruler",
+ config={
+ "annotate_ents": True,
+ "ents_filter": {"@misc": "test_pass_through_filter"},
+ },
+ )
+ ruler.add_patterns(overlapping_patterns)
+ with pytest.raises(ValueError):
+ ruler(nlp.make_doc("foo bar baz"))
diff --git a/spacy/tests/pipeline/test_spancat.py b/spacy/tests/pipeline/test_spancat.py
index 8060bc621..e9db983d3 100644
--- a/spacy/tests/pipeline/test_spancat.py
+++ b/spacy/tests/pipeline/test_spancat.py
@@ -372,24 +372,39 @@ def test_overfitting_IO_overlapping():
def test_zero_suggestions():
- # Test with a suggester that returns 0 suggestions
+ # Test with a suggester that can return 0 suggestions
- @registry.misc("test_zero_suggester")
- def make_zero_suggester():
- def zero_suggester(docs, *, ops=None):
+ @registry.misc("test_mixed_zero_suggester")
+ def make_mixed_zero_suggester():
+ def mixed_zero_suggester(docs, *, ops=None):
if ops is None:
ops = get_current_ops()
- return Ragged(
- ops.xp.zeros((0, 0), dtype="i"), ops.xp.zeros((len(docs),), dtype="i")
- )
+ spans = []
+ lengths = []
+ for doc in docs:
+ if len(doc) > 0 and len(doc) % 2 == 0:
+ spans.append((0, 1))
+ lengths.append(1)
+ else:
+ lengths.append(0)
+ spans = ops.asarray2i(spans)
+ lengths_array = ops.asarray1i(lengths)
+ if len(spans) > 0:
+ output = Ragged(ops.xp.vstack(spans), lengths_array)
+ else:
+ output = Ragged(ops.xp.zeros((0, 0), dtype="i"), lengths_array)
+ return output
- return zero_suggester
+ return mixed_zero_suggester
fix_random_seed(0)
nlp = English()
spancat = nlp.add_pipe(
"spancat",
- config={"suggester": {"@misc": "test_zero_suggester"}, "spans_key": SPAN_KEY},
+ config={
+ "suggester": {"@misc": "test_mixed_zero_suggester"},
+ "spans_key": SPAN_KEY,
+ },
)
train_examples = make_examples(nlp)
optimizer = nlp.initialize(get_examples=lambda: train_examples)
@@ -397,3 +412,35 @@ def test_zero_suggestions():
assert set(spancat.labels) == {"LOC", "PERSON"}
nlp.update(train_examples, sgd=optimizer)
+ # empty doc
+ nlp("")
+ # single doc with zero suggestions
+ nlp("one")
+ # single doc with one suggestion
+ nlp("two two")
+ # batch with mixed zero/one suggestions
+ list(nlp.pipe(["one", "two two", "three three three", "", "four four four four"]))
+ # batch with no suggestions
+ list(nlp.pipe(["", "one", "three three three"]))
+
+
+def test_set_candidates():
+ nlp = Language()
+ spancat = nlp.add_pipe("spancat", config={"spans_key": SPAN_KEY})
+ train_examples = make_examples(nlp)
+ nlp.initialize(get_examples=lambda: train_examples)
+ texts = [
+ "Just a sentence.",
+ "I like London and Berlin",
+ "I like Berlin",
+ "I eat ham.",
+ ]
+
+ docs = [nlp(text) for text in texts]
+ spancat.set_candidates(docs)
+
+ assert len(docs) == len(texts)
+ assert type(docs[0].spans["candidates"]) == SpanGroup
+ assert len(docs[0].spans["candidates"]) == 9
+ assert docs[0].spans["candidates"][0].text == "Just"
+ assert docs[0].spans["candidates"][4].text == "Just a"
diff --git a/spacy/tests/pipeline/test_textcat.py b/spacy/tests/pipeline/test_textcat.py
index 798dd165e..d042f3445 100644
--- a/spacy/tests/pipeline/test_textcat.py
+++ b/spacy/tests/pipeline/test_textcat.py
@@ -360,6 +360,30 @@ def test_label_types(name):
nlp.initialize()
+@pytest.mark.parametrize(
+ "name,get_examples",
+ [
+ ("textcat", make_get_examples_single_label),
+ ("textcat_multilabel", make_get_examples_multi_label),
+ ],
+)
+def test_invalid_label_value(name, get_examples):
+ nlp = Language()
+ textcat = nlp.add_pipe(name)
+ example_getter = get_examples(nlp)
+
+ def invalid_examples():
+ # make one example with an invalid score
+ examples = example_getter()
+ ref = examples[0].reference
+ key = list(ref.cats.keys())[0]
+ ref.cats[key] = 2.0
+ return examples
+
+ with pytest.raises(ValueError):
+ nlp.initialize(get_examples=invalid_examples)
+
+
@pytest.mark.parametrize("name", ["textcat", "textcat_multilabel"])
def test_no_label(name):
nlp = Language()
@@ -382,6 +406,7 @@ def test_implicit_label(name, get_examples):
# fmt: off
+@pytest.mark.slow
@pytest.mark.parametrize(
"name,textcat_config",
[
@@ -390,7 +415,10 @@ def test_implicit_label(name, get_examples):
("textcat", {"@architectures": "spacy.TextCatBOW.v1", "exclusive_classes": True, "no_output_layer": True, "ngram_size": 3}),
("textcat_multilabel", {"@architectures": "spacy.TextCatBOW.v1", "exclusive_classes": False, "no_output_layer": False, "ngram_size": 3}),
("textcat_multilabel", {"@architectures": "spacy.TextCatBOW.v1", "exclusive_classes": False, "no_output_layer": True, "ngram_size": 3}),
- # ENSEMBLE
+ # ENSEMBLE V1
+ ("textcat", {"@architectures": "spacy.TextCatEnsemble.v1", "exclusive_classes": False, "pretrained_vectors": None, "width": 64, "embed_size": 2000, "conv_depth": 2, "window_size": 1, "ngram_size": 1, "dropout": None}),
+ ("textcat_multilabel", {"@architectures": "spacy.TextCatEnsemble.v1", "exclusive_classes": False, "pretrained_vectors": None, "width": 64, "embed_size": 2000, "conv_depth": 2, "window_size": 1, "ngram_size": 1, "dropout": None}),
+ # ENSEMBLE V2
("textcat", {"@architectures": "spacy.TextCatEnsemble.v2", "tok2vec": DEFAULT_TOK2VEC_MODEL, "linear_model": {"@architectures": "spacy.TextCatBOW.v1", "exclusive_classes": True, "no_output_layer": False, "ngram_size": 3}}),
("textcat", {"@architectures": "spacy.TextCatEnsemble.v2", "tok2vec": DEFAULT_TOK2VEC_MODEL, "linear_model": {"@architectures": "spacy.TextCatBOW.v1", "exclusive_classes": True, "no_output_layer": True, "ngram_size": 3}}),
("textcat_multilabel", {"@architectures": "spacy.TextCatEnsemble.v2", "tok2vec": DEFAULT_TOK2VEC_MODEL, "linear_model": {"@architectures": "spacy.TextCatBOW.v1", "exclusive_classes": False, "no_output_layer": False, "ngram_size": 3}}),
@@ -643,15 +671,28 @@ def test_overfitting_IO_multi():
# fmt: off
+@pytest.mark.slow
@pytest.mark.parametrize(
"name,train_data,textcat_config",
[
+ # BOW V1
+ ("textcat_multilabel", TRAIN_DATA_MULTI_LABEL, {"@architectures": "spacy.TextCatBOW.v1", "exclusive_classes": False, "ngram_size": 1, "no_output_layer": False}),
+ ("textcat", TRAIN_DATA_SINGLE_LABEL, {"@architectures": "spacy.TextCatBOW.v1", "exclusive_classes": True, "ngram_size": 4, "no_output_layer": False}),
+ # ENSEMBLE V1
+ ("textcat_multilabel", TRAIN_DATA_MULTI_LABEL, {"@architectures": "spacy.TextCatEnsemble.v1", "exclusive_classes": False, "pretrained_vectors": None, "width": 64, "embed_size": 2000, "conv_depth": 2, "window_size": 1, "ngram_size": 1, "dropout": None}),
+ ("textcat", TRAIN_DATA_SINGLE_LABEL, {"@architectures": "spacy.TextCatEnsemble.v1", "exclusive_classes": False, "pretrained_vectors": None, "width": 64, "embed_size": 2000, "conv_depth": 2, "window_size": 1, "ngram_size": 1, "dropout": None}),
+ # CNN V1
+ ("textcat", TRAIN_DATA_SINGLE_LABEL, {"@architectures": "spacy.TextCatCNN.v1", "tok2vec": DEFAULT_TOK2VEC_MODEL, "exclusive_classes": True}),
+ ("textcat_multilabel", TRAIN_DATA_MULTI_LABEL, {"@architectures": "spacy.TextCatCNN.v1", "tok2vec": DEFAULT_TOK2VEC_MODEL, "exclusive_classes": False}),
+ # BOW V2
("textcat_multilabel", TRAIN_DATA_MULTI_LABEL, {"@architectures": "spacy.TextCatBOW.v2", "exclusive_classes": False, "ngram_size": 1, "no_output_layer": False}),
("textcat", TRAIN_DATA_SINGLE_LABEL, {"@architectures": "spacy.TextCatBOW.v2", "exclusive_classes": True, "ngram_size": 4, "no_output_layer": False}),
("textcat_multilabel", TRAIN_DATA_MULTI_LABEL, {"@architectures": "spacy.TextCatBOW.v2", "exclusive_classes": False, "ngram_size": 3, "no_output_layer": True}),
("textcat", TRAIN_DATA_SINGLE_LABEL, {"@architectures": "spacy.TextCatBOW.v2", "exclusive_classes": True, "ngram_size": 2, "no_output_layer": True}),
+ # ENSEMBLE V2
("textcat_multilabel", TRAIN_DATA_MULTI_LABEL, {"@architectures": "spacy.TextCatEnsemble.v2", "tok2vec": DEFAULT_TOK2VEC_MODEL, "linear_model": {"@architectures": "spacy.TextCatBOW.v2", "exclusive_classes": False, "ngram_size": 1, "no_output_layer": False}}),
("textcat", TRAIN_DATA_SINGLE_LABEL, {"@architectures": "spacy.TextCatEnsemble.v2", "tok2vec": DEFAULT_TOK2VEC_MODEL, "linear_model": {"@architectures": "spacy.TextCatBOW.v2", "exclusive_classes": True, "ngram_size": 5, "no_output_layer": False}}),
+ # CNN V2
("textcat", TRAIN_DATA_SINGLE_LABEL, {"@architectures": "spacy.TextCatCNN.v2", "tok2vec": DEFAULT_TOK2VEC_MODEL, "exclusive_classes": True}),
("textcat_multilabel", TRAIN_DATA_MULTI_LABEL, {"@architectures": "spacy.TextCatCNN.v2", "tok2vec": DEFAULT_TOK2VEC_MODEL, "exclusive_classes": False}),
],
@@ -797,8 +838,8 @@ def test_textcat_loss(multi_label: bool, expected_loss: float):
textcat = nlp.add_pipe("textcat_multilabel")
else:
textcat = nlp.add_pipe("textcat")
- textcat.initialize(lambda: train_examples)
assert isinstance(textcat, TextCategorizer)
+ textcat.initialize(lambda: train_examples)
scores = textcat.model.ops.asarray(
[[0.0, 0.0, 0.0, 1.0], [0.0, 0.0, 1.0, 1.0]], dtype="f" # type: ignore
)
@@ -806,10 +847,10 @@ def test_textcat_loss(multi_label: bool, expected_loss: float):
assert loss == expected_loss
-def test_textcat_threshold():
+def test_textcat_multilabel_threshold():
# Ensure the scorer can be called with a different threshold
nlp = English()
- nlp.add_pipe("textcat")
+ nlp.add_pipe("textcat_multilabel")
train_examples = []
for text, annotations in TRAIN_DATA_SINGLE_LABEL:
@@ -832,7 +873,7 @@ def test_textcat_threshold():
)
pos_f = scores["cats_score"]
assert scores["cats_f_per_type"]["POSITIVE"]["r"] == 1.0
- assert pos_f > macro_f
+ assert pos_f >= macro_f
def test_textcat_multi_threshold():
@@ -854,3 +895,26 @@ def test_textcat_multi_threshold():
scores = nlp.evaluate(train_examples, scorer_cfg={"threshold": 0})
assert scores["cats_f_per_type"]["POSITIVE"]["r"] == 1.0
+
+
+@pytest.mark.parametrize(
+ "component_name,scorer",
+ [
+ ("textcat", "spacy.textcat_scorer.v1"),
+ ("textcat_multilabel", "spacy.textcat_multilabel_scorer.v1"),
+ ],
+)
+def test_textcat_legacy_scorers(component_name, scorer):
+ """Check that legacy scorers are registered and produce the expected score
+ keys."""
+ nlp = English()
+ nlp.add_pipe(component_name, config={"scorer": {"@scorers": scorer}})
+
+ train_examples = []
+ for text, annotations in TRAIN_DATA_SINGLE_LABEL:
+ train_examples.append(Example.from_dict(nlp.make_doc(text), annotations))
+ nlp.initialize(get_examples=lambda: train_examples)
+
+ # score the model (it's not actually trained but that doesn't matter)
+ scores = nlp.evaluate(train_examples)
+ assert 0 <= scores["cats_score"] <= 1
diff --git a/spacy/tests/pipeline/test_tok2vec.py b/spacy/tests/pipeline/test_tok2vec.py
index a5ac85e1e..e423d9a19 100644
--- a/spacy/tests/pipeline/test_tok2vec.py
+++ b/spacy/tests/pipeline/test_tok2vec.py
@@ -1,13 +1,13 @@
import pytest
from spacy.ml.models.tok2vec import build_Tok2Vec_model
-from spacy.ml.models.tok2vec import MultiHashEmbed, CharacterEmbed
-from spacy.ml.models.tok2vec import MishWindowEncoder, MaxoutWindowEncoder
+from spacy.ml.models.tok2vec import MultiHashEmbed, MaxoutWindowEncoder
from spacy.pipeline.tok2vec import Tok2Vec, Tok2VecListener
from spacy.vocab import Vocab
from spacy.tokens import Doc
from spacy.training import Example
from spacy import util
from spacy.lang.en import English
+from spacy.util import registry
from thinc.api import Config, get_current_ops
from numpy.testing import assert_array_equal
@@ -55,24 +55,41 @@ def test_tok2vec_batch_sizes(batch_size, width, embed_size):
assert doc_vec.shape == (len(doc), width)
+@pytest.mark.slow
+@pytest.mark.parametrize("width", [8])
@pytest.mark.parametrize(
- "width,embed_arch,embed_config,encode_arch,encode_config",
+ "embed_arch,embed_config",
# fmt: off
[
- (8, MultiHashEmbed, {"rows": [100, 100], "attrs": ["SHAPE", "LOWER"], "include_static_vectors": False}, MaxoutWindowEncoder, {"window_size": 1, "maxout_pieces": 3, "depth": 2}),
- (8, MultiHashEmbed, {"rows": [100, 20], "attrs": ["ORTH", "PREFIX"], "include_static_vectors": False}, MishWindowEncoder, {"window_size": 1, "depth": 6}),
- (8, CharacterEmbed, {"rows": 100, "nM": 64, "nC": 8, "include_static_vectors": False}, MaxoutWindowEncoder, {"window_size": 1, "maxout_pieces": 3, "depth": 3}),
- (8, CharacterEmbed, {"rows": 100, "nM": 16, "nC": 2, "include_static_vectors": False}, MishWindowEncoder, {"window_size": 1, "depth": 3}),
+ ("spacy.MultiHashEmbed.v1", {"rows": [100, 100], "attrs": ["SHAPE", "LOWER"], "include_static_vectors": False}),
+ ("spacy.MultiHashEmbed.v1", {"rows": [100, 20], "attrs": ["ORTH", "PREFIX"], "include_static_vectors": False}),
+ ("spacy.CharacterEmbed.v1", {"rows": 100, "nM": 64, "nC": 8, "include_static_vectors": False}),
+ ("spacy.CharacterEmbed.v1", {"rows": 100, "nM": 16, "nC": 2, "include_static_vectors": False}),
],
# fmt: on
)
-def test_tok2vec_configs(width, embed_arch, embed_config, encode_arch, encode_config):
+@pytest.mark.parametrize(
+ "tok2vec_arch,encode_arch,encode_config",
+ # fmt: off
+ [
+ ("spacy.Tok2Vec.v1", "spacy.MaxoutWindowEncoder.v1", {"window_size": 1, "maxout_pieces": 3, "depth": 2}),
+ ("spacy.Tok2Vec.v2", "spacy.MaxoutWindowEncoder.v2", {"window_size": 1, "maxout_pieces": 3, "depth": 2}),
+ ("spacy.Tok2Vec.v1", "spacy.MishWindowEncoder.v1", {"window_size": 1, "depth": 6}),
+ ("spacy.Tok2Vec.v2", "spacy.MishWindowEncoder.v2", {"window_size": 1, "depth": 6}),
+ ],
+ # fmt: on
+)
+def test_tok2vec_configs(
+ width, tok2vec_arch, embed_arch, embed_config, encode_arch, encode_config
+):
+ embed = registry.get("architectures", embed_arch)
+ encode = registry.get("architectures", encode_arch)
+ tok2vec_model = registry.get("architectures", tok2vec_arch)
+
embed_config["width"] = width
encode_config["width"] = width
docs = get_batch(3)
- tok2vec = build_Tok2Vec_model(
- embed_arch(**embed_config), encode_arch(**encode_config)
- )
+ tok2vec = tok2vec_model(embed(**embed_config), encode(**encode_config))
tok2vec.initialize(docs)
vectors, backprop = tok2vec.begin_update(docs)
assert len(vectors) == len(docs)
@@ -100,7 +117,7 @@ cfg_string = """
factory = "tagger"
[components.tagger.model]
- @architectures = "spacy.Tagger.v1"
+ @architectures = "spacy.Tagger.v2"
nO = null
[components.tagger.model.tok2vec]
@@ -213,6 +230,97 @@ def test_tok2vec_listener_callback():
assert get_dX(Y) is not None
+def test_tok2vec_listener_overfitting():
+ """Test that a pipeline with a listener properly overfits, even if 'tok2vec' is in the annotating components"""
+ orig_config = Config().from_str(cfg_string)
+ nlp = util.load_model_from_config(orig_config, auto_fill=True, validate=True)
+ train_examples = []
+ for t in TRAIN_DATA:
+ train_examples.append(Example.from_dict(nlp.make_doc(t[0]), t[1]))
+ optimizer = nlp.initialize(get_examples=lambda: train_examples)
+
+ for i in range(50):
+ losses = {}
+ nlp.update(train_examples, sgd=optimizer, losses=losses, annotates=["tok2vec"])
+ assert losses["tagger"] < 0.00001
+
+ # test the trained model
+ test_text = "I like blue eggs"
+ doc = nlp(test_text)
+ assert doc[0].tag_ == "N"
+ assert doc[1].tag_ == "V"
+ assert doc[2].tag_ == "J"
+ assert doc[3].tag_ == "N"
+
+ # Also test the results are still the same after IO
+ with make_tempdir() as tmp_dir:
+ nlp.to_disk(tmp_dir)
+ nlp2 = util.load_model_from_path(tmp_dir)
+ doc2 = nlp2(test_text)
+ assert doc2[0].tag_ == "N"
+ assert doc2[1].tag_ == "V"
+ assert doc2[2].tag_ == "J"
+ assert doc2[3].tag_ == "N"
+
+
+def test_tok2vec_frozen_not_annotating():
+ """Test that a pipeline with a frozen tok2vec raises an error when the tok2vec is not annotating"""
+ orig_config = Config().from_str(cfg_string)
+ nlp = util.load_model_from_config(orig_config, auto_fill=True, validate=True)
+ train_examples = []
+ for t in TRAIN_DATA:
+ train_examples.append(Example.from_dict(nlp.make_doc(t[0]), t[1]))
+ optimizer = nlp.initialize(get_examples=lambda: train_examples)
+
+ for i in range(2):
+ losses = {}
+ with pytest.raises(
+ ValueError, match=r"the tok2vec embedding layer is not updated"
+ ):
+ nlp.update(
+ train_examples, sgd=optimizer, losses=losses, exclude=["tok2vec"]
+ )
+
+
+def test_tok2vec_frozen_overfitting():
+ """Test that a pipeline with a frozen & annotating tok2vec can still overfit"""
+ orig_config = Config().from_str(cfg_string)
+ nlp = util.load_model_from_config(orig_config, auto_fill=True, validate=True)
+ train_examples = []
+ for t in TRAIN_DATA:
+ train_examples.append(Example.from_dict(nlp.make_doc(t[0]), t[1]))
+ optimizer = nlp.initialize(get_examples=lambda: train_examples)
+
+ for i in range(100):
+ losses = {}
+ nlp.update(
+ train_examples,
+ sgd=optimizer,
+ losses=losses,
+ exclude=["tok2vec"],
+ annotates=["tok2vec"],
+ )
+ assert losses["tagger"] < 0.0001
+
+ # test the trained model
+ test_text = "I like blue eggs"
+ doc = nlp(test_text)
+ assert doc[0].tag_ == "N"
+ assert doc[1].tag_ == "V"
+ assert doc[2].tag_ == "J"
+ assert doc[3].tag_ == "N"
+
+ # Also test the results are still the same after IO
+ with make_tempdir() as tmp_dir:
+ nlp.to_disk(tmp_dir)
+ nlp2 = util.load_model_from_path(tmp_dir)
+ doc2 = nlp2(test_text)
+ assert doc2[0].tag_ == "N"
+ assert doc2[1].tag_ == "V"
+ assert doc2[2].tag_ == "J"
+ assert doc2[3].tag_ == "N"
+
+
def test_replace_listeners():
orig_config = Config().from_str(cfg_string)
nlp = util.load_model_from_config(orig_config, auto_fill=True, validate=True)
@@ -263,7 +371,7 @@ cfg_string_multi = """
factory = "tagger"
[components.tagger.model]
- @architectures = "spacy.Tagger.v1"
+ @architectures = "spacy.Tagger.v2"
nO = null
[components.tagger.model.tok2vec]
@@ -373,7 +481,7 @@ cfg_string_multi_textcat = """
factory = "tagger"
[components.tagger.model]
- @architectures = "spacy.Tagger.v1"
+ @architectures = "spacy.Tagger.v2"
nO = null
[components.tagger.model.tok2vec]
diff --git a/spacy/tests/serialize/test_resource_warning.py b/spacy/tests/serialize/test_resource_warning.py
index a00b2a688..38701c6d9 100644
--- a/spacy/tests/serialize/test_resource_warning.py
+++ b/spacy/tests/serialize/test_resource_warning.py
@@ -3,7 +3,7 @@ from unittest import TestCase
import pytest
import srsly
from numpy import zeros
-from spacy.kb import KnowledgeBase, Writer
+from spacy.kb.kb_in_memory import InMemoryLookupKB, Writer
from spacy.vectors import Vectors
from spacy.language import Language
from spacy.pipeline import TrainablePipe
@@ -71,7 +71,7 @@ def entity_linker():
nlp = Language()
def create_kb(vocab):
- kb = KnowledgeBase(vocab, entity_vector_length=1)
+ kb = InMemoryLookupKB(vocab, entity_vector_length=1)
kb.add_entity("test", 0.0, zeros((1, 1), dtype="f"))
return kb
@@ -120,7 +120,7 @@ def test_writer_with_path_py35():
def test_save_and_load_knowledge_base():
nlp = Language()
- kb = KnowledgeBase(nlp.vocab, entity_vector_length=1)
+ kb = InMemoryLookupKB(nlp.vocab, entity_vector_length=1)
with make_tempdir() as d:
path = d / "kb"
try:
@@ -129,7 +129,7 @@ def test_save_and_load_knowledge_base():
pytest.fail(str(e))
try:
- kb_loaded = KnowledgeBase(nlp.vocab, entity_vector_length=1)
+ kb_loaded = InMemoryLookupKB(nlp.vocab, entity_vector_length=1)
kb_loaded.from_disk(path)
except Exception as e:
pytest.fail(str(e))
diff --git a/spacy/tests/serialize/test_serialize_config.py b/spacy/tests/serialize/test_serialize_config.py
index 1d50fd1d1..85e6f8b2c 100644
--- a/spacy/tests/serialize/test_serialize_config.py
+++ b/spacy/tests/serialize/test_serialize_config.py
@@ -59,7 +59,7 @@ subword_features = true
factory = "tagger"
[components.tagger.model]
-@architectures = "spacy.Tagger.v1"
+@architectures = "spacy.Tagger.v2"
[components.tagger.model.tok2vec]
@architectures = "spacy.Tok2VecListener.v1"
@@ -110,7 +110,7 @@ subword_features = true
factory = "tagger"
[components.tagger.model]
-@architectures = "spacy.Tagger.v1"
+@architectures = "spacy.Tagger.v2"
[components.tagger.model.tok2vec]
@architectures = "spacy.Tok2VecListener.v1"
diff --git a/spacy/tests/serialize/test_serialize_kb.py b/spacy/tests/serialize/test_serialize_kb.py
index 1e0ae3c76..8d3653ab1 100644
--- a/spacy/tests/serialize/test_serialize_kb.py
+++ b/spacy/tests/serialize/test_serialize_kb.py
@@ -2,7 +2,7 @@ from typing import Callable
from spacy import util
from spacy.util import ensure_path, registry, load_model_from_config
-from spacy.kb import KnowledgeBase
+from spacy.kb.kb_in_memory import InMemoryLookupKB
from spacy.vocab import Vocab
from thinc.api import Config
@@ -22,7 +22,7 @@ def test_serialize_kb_disk(en_vocab):
dir_path.mkdir()
file_path = dir_path / "kb"
kb1.to_disk(str(file_path))
- kb2 = KnowledgeBase(vocab=en_vocab, entity_vector_length=3)
+ kb2 = InMemoryLookupKB(vocab=en_vocab, entity_vector_length=3)
kb2.from_disk(str(file_path))
# final assertions
@@ -30,7 +30,7 @@ def test_serialize_kb_disk(en_vocab):
def _get_dummy_kb(vocab):
- kb = KnowledgeBase(vocab, entity_vector_length=3)
+ kb = InMemoryLookupKB(vocab, entity_vector_length=3)
kb.add_entity(entity="Q53", freq=33, entity_vector=[0, 5, 3])
kb.add_entity(entity="Q17", freq=2, entity_vector=[7, 1, 0])
kb.add_entity(entity="Q007", freq=7, entity_vector=[0, 0, 7])
@@ -104,7 +104,7 @@ def test_serialize_subclassed_kb():
custom_field = 666
"""
- class SubKnowledgeBase(KnowledgeBase):
+ class SubInMemoryLookupKB(InMemoryLookupKB):
def __init__(self, vocab, entity_vector_length, custom_field):
super().__init__(vocab, entity_vector_length)
self.custom_field = custom_field
@@ -112,9 +112,9 @@ def test_serialize_subclassed_kb():
@registry.misc("spacy.CustomKB.v1")
def custom_kb(
entity_vector_length: int, custom_field: int
- ) -> Callable[[Vocab], KnowledgeBase]:
+ ) -> Callable[[Vocab], InMemoryLookupKB]:
def custom_kb_factory(vocab):
- kb = SubKnowledgeBase(
+ kb = SubInMemoryLookupKB(
vocab=vocab,
entity_vector_length=entity_vector_length,
custom_field=custom_field,
@@ -129,7 +129,7 @@ def test_serialize_subclassed_kb():
nlp.initialize()
entity_linker = nlp.get_pipe("entity_linker")
- assert type(entity_linker.kb) == SubKnowledgeBase
+ assert type(entity_linker.kb) == SubInMemoryLookupKB
assert entity_linker.kb.entity_vector_length == 342
assert entity_linker.kb.custom_field == 666
@@ -139,6 +139,6 @@ def test_serialize_subclassed_kb():
nlp2 = util.load_model_from_path(tmp_dir)
entity_linker2 = nlp2.get_pipe("entity_linker")
# After IO, the KB is the standard one
- assert type(entity_linker2.kb) == KnowledgeBase
+ assert type(entity_linker2.kb) == InMemoryLookupKB
assert entity_linker2.kb.entity_vector_length == 342
assert not hasattr(entity_linker2.kb, "custom_field")
diff --git a/spacy/tests/serialize/test_serialize_language.py b/spacy/tests/serialize/test_serialize_language.py
index 6e7fa0e4e..c03287548 100644
--- a/spacy/tests/serialize/test_serialize_language.py
+++ b/spacy/tests/serialize/test_serialize_language.py
@@ -70,7 +70,7 @@ factory = "ner"
factory = "tagger"
[components.tagger.model]
-@architectures = "spacy.Tagger.v1"
+@architectures = "spacy.Tagger.v2"
nO = null
[components.tagger.model.tok2vec]
diff --git a/spacy/tests/serialize/test_serialize_span_groups.py b/spacy/tests/serialize/test_serialize_span_groups.py
new file mode 100644
index 000000000..85313fcdc
--- /dev/null
+++ b/spacy/tests/serialize/test_serialize_span_groups.py
@@ -0,0 +1,161 @@
+import pytest
+
+from spacy.tokens import Span, SpanGroup
+from spacy.tokens._dict_proxies import SpanGroups
+
+
+@pytest.mark.issue(10685)
+def test_issue10685(en_tokenizer):
+ """Test `SpanGroups` de/serialization"""
+ # Start with a Doc with no SpanGroups
+ doc = en_tokenizer("Will it blend?")
+
+ # Test empty `SpanGroups` de/serialization:
+ assert len(doc.spans) == 0
+ doc.spans.from_bytes(doc.spans.to_bytes())
+ assert len(doc.spans) == 0
+
+ # Test non-empty `SpanGroups` de/serialization:
+ doc.spans["test"] = SpanGroup(doc, name="test", spans=[doc[0:1]])
+ doc.spans["test2"] = SpanGroup(doc, name="test", spans=[doc[1:2]])
+
+ def assert_spangroups():
+ assert len(doc.spans) == 2
+ assert doc.spans["test"].name == "test"
+ assert doc.spans["test2"].name == "test"
+ assert list(doc.spans["test"]) == [doc[0:1]]
+ assert list(doc.spans["test2"]) == [doc[1:2]]
+
+ # Sanity check the currently-expected behavior
+ assert_spangroups()
+
+ # Now test serialization/deserialization:
+ doc.spans.from_bytes(doc.spans.to_bytes())
+
+ assert_spangroups()
+
+
+def test_span_groups_serialization_mismatches(en_tokenizer):
+ """Test the serialization of multiple mismatching `SpanGroups` keys and `SpanGroup.name`s"""
+ doc = en_tokenizer("How now, brown cow?")
+ # Some variety:
+ # 1 SpanGroup where its name matches its key
+ # 2 SpanGroups that have the same name--which is not a key
+ # 2 SpanGroups that have the same name--which is a key
+ # 1 SpanGroup that is a value for 2 different keys (where its name is a key)
+ # 1 SpanGroup that is a value for 2 different keys (where its name is not a key)
+ groups = doc.spans
+ groups["key1"] = SpanGroup(doc, name="key1", spans=[doc[0:1], doc[1:2]])
+ groups["key2"] = SpanGroup(doc, name="too", spans=[doc[3:4], doc[4:5]])
+ groups["key3"] = SpanGroup(doc, name="too", spans=[doc[1:2], doc[0:1]])
+ groups["key4"] = SpanGroup(doc, name="key4", spans=[doc[0:1]])
+ groups["key5"] = SpanGroup(doc, name="key4", spans=[doc[0:1]])
+ sg6 = SpanGroup(doc, name="key6", spans=[doc[0:1]])
+ groups["key6"] = sg6
+ groups["key7"] = sg6
+ sg8 = SpanGroup(doc, name="also", spans=[doc[1:2]])
+ groups["key8"] = sg8
+ groups["key9"] = sg8
+
+ regroups = SpanGroups(doc).from_bytes(groups.to_bytes())
+
+ # Assert regroups == groups
+ assert regroups.keys() == groups.keys()
+ for key, regroup in regroups.items():
+ # Assert regroup == groups[key]
+ assert regroup.name == groups[key].name
+ assert list(regroup) == list(groups[key])
+
+
+@pytest.mark.parametrize(
+ "spans_bytes,doc_text,expected_spangroups,expected_warning",
+ # The bytestrings below were generated from an earlier version of spaCy
+ # that serialized `SpanGroups` as a list of SpanGroup bytes (via SpanGroups.to_bytes).
+ # Comments preceding the bytestrings indicate from what Doc they were created.
+ [
+ # Empty SpanGroups:
+ (b"\x90", "", {}, False),
+ # doc = nlp("Will it blend?")
+ # doc.spans['test'] = SpanGroup(doc, name='test', spans=[doc[0:1]])
+ (
+ b"\x91\xc4C\x83\xa4name\xa4test\xa5attrs\x80\xa5spans\x91\xc4(\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x04",
+ "Will it blend?",
+ {"test": {"name": "test", "spans": [(0, 1)]}},
+ False,
+ ),
+ # doc = nlp("Will it blend?")
+ # doc.spans['test'] = SpanGroup(doc, name='test', spans=[doc[0:1]])
+ # doc.spans['test2'] = SpanGroup(doc, name='test', spans=[doc[1:2]])
+ (
+ b"\x92\xc4C\x83\xa4name\xa4test\xa5attrs\x80\xa5spans\x91\xc4(\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x04\xc4C\x83\xa4name\xa4test\xa5attrs\x80\xa5spans\x91\xc4(\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x02\x00\x00\x00\x05\x00\x00\x00\x07",
+ "Will it blend?",
+ # We expect only 1 SpanGroup to be in doc.spans in this example
+ # because there are 2 `SpanGroup`s that have the same .name. See #10685.
+ {"test": {"name": "test", "spans": [(1, 2)]}},
+ True,
+ ),
+ # doc = nlp('How now, brown cow?')
+ # doc.spans['key1'] = SpanGroup(doc, name='key1', spans=[doc[0:1], doc[1:2]])
+ # doc.spans['key2'] = SpanGroup(doc, name='too', spans=[doc[3:4], doc[4:5]])
+ # doc.spans['key3'] = SpanGroup(doc, name='too', spans=[doc[1:2], doc[0:1]])
+ # doc.spans['key4'] = SpanGroup(doc, name='key4', spans=[doc[0:1]])
+ # doc.spans['key5'] = SpanGroup(doc, name='key4', spans=[doc[0:1]])
+ (
+ b"\x95\xc4m\x83\xa4name\xa4key1\xa5attrs\x80\xa5spans\x92\xc4(\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x03\xc4(\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x02\x00\x00\x00\x04\x00\x00\x00\x07\xc4l\x83\xa4name\xa3too\xa5attrs\x80\xa5spans\x92\xc4(\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x03\x00\x00\x00\x04\x00\x00\x00\t\x00\x00\x00\x0e\xc4(\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x05\x00\x00\x00\x0f\x00\x00\x00\x12\xc4l\x83\xa4name\xa3too\xa5attrs\x80\xa5spans\x92\xc4(\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x02\x00\x00\x00\x04\x00\x00\x00\x07\xc4(\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x03\xc4C\x83\xa4name\xa4key4\xa5attrs\x80\xa5spans\x91\xc4(\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x03\xc4C\x83\xa4name\xa4key4\xa5attrs\x80\xa5spans\x91\xc4(\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x03",
+ "How now, brown cow?",
+ {
+ "key1": {"name": "key1", "spans": [(0, 1), (1, 2)]},
+ "too": {"name": "too", "spans": [(1, 2), (0, 1)]},
+ "key4": {"name": "key4", "spans": [(0, 1)]},
+ },
+ True,
+ ),
+ ],
+)
+def test_deserialize_span_groups_compat(
+ en_tokenizer, spans_bytes, doc_text, expected_spangroups, expected_warning
+):
+ """Test backwards-compatibility of `SpanGroups` deserialization.
+ This uses serializations (bytes) from a prior version of spaCy (before 3.3.1).
+
+ spans_bytes (bytes): Serialized `SpanGroups` object.
+ doc_text (str): Doc text.
+ expected_spangroups (dict):
+ Dict mapping every expected (after deserialization) `SpanGroups` key
+ to a SpanGroup's "args", where a SpanGroup's args are given as a dict:
+ {"name": span_group.name,
+ "spans": [(span0.start, span0.end), ...]}
+ expected_warning (bool): Whether a warning is to be expected from .from_bytes()
+ --i.e. if more than 1 SpanGroup has the same .name within the `SpanGroups`.
+ """
+ doc = en_tokenizer(doc_text)
+
+ if expected_warning:
+ with pytest.warns(UserWarning):
+ doc.spans.from_bytes(spans_bytes)
+ else:
+ # TODO: explicitly check for lack of a warning
+ doc.spans.from_bytes(spans_bytes)
+
+ assert doc.spans.keys() == expected_spangroups.keys()
+ for name, spangroup_args in expected_spangroups.items():
+ assert doc.spans[name].name == spangroup_args["name"]
+ spans = [Span(doc, start, end) for start, end in spangroup_args["spans"]]
+ assert list(doc.spans[name]) == spans
+
+
+def test_span_groups_serialization(en_tokenizer):
+ doc = en_tokenizer("0 1 2 3 4 5 6")
+ span_groups = SpanGroups(doc)
+ spans = [doc[0:2], doc[1:3]]
+ sg1 = SpanGroup(doc, spans=spans)
+ span_groups["key1"] = sg1
+ span_groups["key2"] = sg1
+ span_groups["key3"] = []
+ reloaded_span_groups = SpanGroups(doc).from_bytes(span_groups.to_bytes())
+ assert span_groups.keys() == reloaded_span_groups.keys()
+ for key, value in span_groups.items():
+ assert all(
+ span == reloaded_span
+ for span, reloaded_span in zip(span_groups[key], reloaded_span_groups[key])
+ )
diff --git a/spacy/tests/serialize/test_serialize_tokenizer.py b/spacy/tests/serialize/test_serialize_tokenizer.py
index e271f7707..9b74d7721 100644
--- a/spacy/tests/serialize/test_serialize_tokenizer.py
+++ b/spacy/tests/serialize/test_serialize_tokenizer.py
@@ -70,6 +70,7 @@ def test_issue4190():
suffix_search=suffix_re.search,
infix_finditer=infix_re.finditer,
token_match=nlp.tokenizer.token_match,
+ faster_heuristics=False,
)
nlp.tokenizer = new_tokenizer
@@ -90,6 +91,7 @@ def test_issue4190():
doc_2 = nlp_2(test_string)
result_2 = [token.text for token in doc_2]
assert result_1b == result_2
+ assert nlp_2.tokenizer.faster_heuristics is False
def test_serialize_custom_tokenizer(en_vocab, en_tokenizer):
diff --git a/spacy/tests/test_cli.py b/spacy/tests/test_cli.py
index ec512b839..d00f66c60 100644
--- a/spacy/tests/test_cli.py
+++ b/spacy/tests/test_cli.py
@@ -1,5 +1,13 @@
import os
+import math
+from collections import Counter
+from typing import Tuple, List, Dict, Any
+import pkg_resources
+import time
+from pathlib import Path
+import spacy
+import numpy
import pytest
import srsly
from click import NoSuchOption
@@ -8,22 +16,32 @@ from thinc.api import Config, ConfigValidationError
from spacy import about
from spacy.cli import info
-from spacy.cli._util import is_subpath_of, load_project_config
+from spacy.cli._util import is_subpath_of, load_project_config, walk_directory
from spacy.cli._util import parse_config_overrides, string_to_list
from spacy.cli._util import substitute_project_variables
from spacy.cli._util import validate_project_commands
+from spacy.cli._util import upload_file, download_file
from spacy.cli.debug_data import _compile_gold, _get_labels_from_model
from spacy.cli.debug_data import _get_labels_from_spancat
+from spacy.cli.debug_data import _get_distribution, _get_kl_divergence
+from spacy.cli.debug_data import _get_span_characteristics
+from spacy.cli.debug_data import _print_span_characteristics
+from spacy.cli.debug_data import _get_spans_length_freq_dist
from spacy.cli.download import get_compatibility, get_version
from spacy.cli.init_config import RECOMMENDATIONS, init_config, fill_config
from spacy.cli.package import get_third_party_dependencies
from spacy.cli.package import _is_permitted_package_name
+from spacy.cli.project.remote_storage import RemoteStorage
+from spacy.cli.project.run import _check_requirements
from spacy.cli.validate import get_model_pkgs
+from spacy.cli.apply import apply
+from spacy.cli.find_threshold import find_threshold
from spacy.lang.en import English
from spacy.lang.nl import Dutch
from spacy.language import Language
from spacy.schemas import ProjectConfigSchema, RecommendationSchema, validate
-from spacy.tokens import Doc
+from spacy.tokens import Doc, DocBin
+from spacy.tokens.span import Span
from spacy.training import Example, docs_to_json, offsets_to_biluo_tags
from spacy.training.converters import conll_ner_to_docs, conllu_to_docs
from spacy.training.converters import iob_to_docs
@@ -108,6 +126,25 @@ def test_issue7055():
assert "model" in filled_cfg["components"]["ner"]
+@pytest.mark.issue(11235)
+def test_issue11235():
+ """
+ Test that the cli handles interpolation in the directory names correctly when loading project config.
+ """
+ lang_var = "en"
+ variables = {"lang": lang_var}
+ commands = [{"name": "x", "script": ["hello ${vars.lang}"]}]
+ directories = ["cfg", "${vars.lang}_model"]
+ project = {"commands": commands, "vars": variables, "directories": directories}
+ with make_tempdir() as d:
+ srsly.write_yaml(d / "project.yml", project)
+ cfg = load_project_config(d)
+ # Check that the directories are interpolated and created correctly
+ assert os.path.exists(d / "cfg")
+ assert os.path.exists(d / f"{lang_var}_model")
+ assert cfg["commands"][0]["script"][0] == f"hello {lang_var}"
+
+
def test_cli_info():
nlp = Dutch()
nlp.add_pipe("textcat")
@@ -217,7 +254,6 @@ def test_cli_converters_conllu_to_docs_subtokens():
sent = converted[0]["paragraphs"][0]["sentences"][0]
assert len(sent["tokens"]) == 4
tokens = sent["tokens"]
- print(tokens)
assert [t["orth"] for t in tokens] == ["Dommer", "FE", "avstår", "."]
assert [t["tag"] for t in tokens] == [
"NOUN__Definite=Ind|Gender=Masc|Number=Sing",
@@ -342,6 +378,7 @@ def test_project_config_validation_full():
"assets": [
{
"dest": "x",
+ "extra": True,
"url": "https://example.com",
"checksum": "63373dd656daa1fd3043ce166a59474c",
},
@@ -353,6 +390,12 @@ def test_project_config_validation_full():
"path": "y",
},
},
+ {
+ "dest": "z",
+ "extra": False,
+ "url": "https://example.com",
+ "checksum": "63373dd656daa1fd3043ce166a59474c",
+ },
],
"commands": [
{
@@ -734,3 +777,433 @@ def test_debug_data_compile_gold():
eg = Example(pred, ref)
data = _compile_gold([eg], ["ner"], nlp, True)
assert data["boundary_cross_ents"] == 1
+
+
+def test_debug_data_compile_gold_for_spans():
+ nlp = English()
+ spans_key = "sc"
+
+ pred = Doc(nlp.vocab, words=["Welcome", "to", "the", "Bank", "of", "China", "."])
+ pred.spans[spans_key] = [Span(pred, 3, 6, "ORG"), Span(pred, 5, 6, "GPE")]
+ ref = Doc(nlp.vocab, words=["Welcome", "to", "the", "Bank", "of", "China", "."])
+ ref.spans[spans_key] = [Span(ref, 3, 6, "ORG"), Span(ref, 5, 6, "GPE")]
+ eg = Example(pred, ref)
+
+ data = _compile_gold([eg], ["spancat"], nlp, True)
+
+ assert data["spancat"][spans_key] == Counter({"ORG": 1, "GPE": 1})
+ assert data["spans_length"][spans_key] == {"ORG": [3], "GPE": [1]}
+ assert data["spans_per_type"][spans_key] == {
+ "ORG": [Span(ref, 3, 6, "ORG")],
+ "GPE": [Span(ref, 5, 6, "GPE")],
+ }
+ assert data["sb_per_type"][spans_key] == {
+ "ORG": {"start": [ref[2:3]], "end": [ref[6:7]]},
+ "GPE": {"start": [ref[4:5]], "end": [ref[6:7]]},
+ }
+
+
+def test_frequency_distribution_is_correct():
+ nlp = English()
+ docs = [
+ Doc(nlp.vocab, words=["Bank", "of", "China"]),
+ Doc(nlp.vocab, words=["China"]),
+ ]
+
+ expected = Counter({"china": 0.5, "bank": 0.25, "of": 0.25})
+ freq_distribution = _get_distribution(docs, normalize=True)
+ assert freq_distribution == expected
+
+
+def test_kl_divergence_computation_is_correct():
+ p = Counter({"a": 0.5, "b": 0.25})
+ q = Counter({"a": 0.25, "b": 0.50, "c": 0.15, "d": 0.10})
+ result = _get_kl_divergence(p, q)
+ expected = 0.1733
+ assert math.isclose(result, expected, rel_tol=1e-3)
+
+
+def test_get_span_characteristics_return_value():
+ nlp = English()
+ spans_key = "sc"
+
+ pred = Doc(nlp.vocab, words=["Welcome", "to", "the", "Bank", "of", "China", "."])
+ pred.spans[spans_key] = [Span(pred, 3, 6, "ORG"), Span(pred, 5, 6, "GPE")]
+ ref = Doc(nlp.vocab, words=["Welcome", "to", "the", "Bank", "of", "China", "."])
+ ref.spans[spans_key] = [Span(ref, 3, 6, "ORG"), Span(ref, 5, 6, "GPE")]
+ eg = Example(pred, ref)
+
+ examples = [eg]
+ data = _compile_gold(examples, ["spancat"], nlp, True)
+ span_characteristics = _get_span_characteristics(
+ examples=examples, compiled_gold=data, spans_key=spans_key
+ )
+
+ assert {"sd", "bd", "lengths"}.issubset(span_characteristics.keys())
+ assert span_characteristics["min_length"] == 1
+ assert span_characteristics["max_length"] == 3
+
+
+def test_ensure_print_span_characteristics_wont_fail():
+ """Test if interface between two methods aren't destroyed if refactored"""
+ nlp = English()
+ spans_key = "sc"
+
+ pred = Doc(nlp.vocab, words=["Welcome", "to", "the", "Bank", "of", "China", "."])
+ pred.spans[spans_key] = [Span(pred, 3, 6, "ORG"), Span(pred, 5, 6, "GPE")]
+ ref = Doc(nlp.vocab, words=["Welcome", "to", "the", "Bank", "of", "China", "."])
+ ref.spans[spans_key] = [Span(ref, 3, 6, "ORG"), Span(ref, 5, 6, "GPE")]
+ eg = Example(pred, ref)
+
+ examples = [eg]
+ data = _compile_gold(examples, ["spancat"], nlp, True)
+ span_characteristics = _get_span_characteristics(
+ examples=examples, compiled_gold=data, spans_key=spans_key
+ )
+ _print_span_characteristics(span_characteristics)
+
+
+@pytest.mark.parametrize("threshold", [70, 80, 85, 90, 95])
+def test_span_length_freq_dist_threshold_must_be_correct(threshold):
+ sample_span_lengths = {
+ "span_type_1": [1, 4, 4, 5],
+ "span_type_2": [5, 3, 3, 2],
+ "span_type_3": [3, 1, 3, 3],
+ }
+ span_freqs = _get_spans_length_freq_dist(sample_span_lengths, threshold)
+ assert sum(span_freqs.values()) >= threshold
+
+
+def test_span_length_freq_dist_output_must_be_correct():
+ sample_span_lengths = {
+ "span_type_1": [1, 4, 4, 5],
+ "span_type_2": [5, 3, 3, 2],
+ "span_type_3": [3, 1, 3, 3],
+ }
+ threshold = 90
+ span_freqs = _get_spans_length_freq_dist(sample_span_lengths, threshold)
+ assert sum(span_freqs.values()) >= threshold
+ assert list(span_freqs.keys()) == [3, 1, 4, 5, 2]
+
+
+def test_applycli_empty_dir():
+ with make_tempdir() as data_path:
+ output = data_path / "test.spacy"
+ apply(data_path, output, "blank:en", "text", 1, 1)
+
+
+def test_applycli_docbin():
+ with make_tempdir() as data_path:
+ output = data_path / "testout.spacy"
+ nlp = spacy.blank("en")
+ doc = nlp("testing apply cli.")
+ # test empty DocBin case
+ docbin = DocBin()
+ docbin.to_disk(data_path / "testin.spacy")
+ apply(data_path, output, "blank:en", "text", 1, 1)
+ docbin.add(doc)
+ docbin.to_disk(data_path / "testin.spacy")
+ apply(data_path, output, "blank:en", "text", 1, 1)
+
+
+def test_applycli_jsonl():
+ with make_tempdir() as data_path:
+ output = data_path / "testout.spacy"
+ data = [{"field": "Testing apply cli.", "key": 234}]
+ data2 = [{"field": "234"}]
+ srsly.write_jsonl(data_path / "test.jsonl", data)
+ apply(data_path, output, "blank:en", "field", 1, 1)
+ srsly.write_jsonl(data_path / "test2.jsonl", data2)
+ apply(data_path, output, "blank:en", "field", 1, 1)
+
+
+def test_applycli_txt():
+ with make_tempdir() as data_path:
+ output = data_path / "testout.spacy"
+ with open(data_path / "test.foo", "w") as ftest:
+ ftest.write("Testing apply cli.")
+ apply(data_path, output, "blank:en", "text", 1, 1)
+
+
+def test_applycli_mixed():
+ with make_tempdir() as data_path:
+ output = data_path / "testout.spacy"
+ text = "Testing apply cli"
+ nlp = spacy.blank("en")
+ doc = nlp(text)
+ jsonl_data = [{"text": text}]
+ srsly.write_jsonl(data_path / "test.jsonl", jsonl_data)
+ docbin = DocBin()
+ docbin.add(doc)
+ docbin.to_disk(data_path / "testin.spacy")
+ with open(data_path / "test.txt", "w") as ftest:
+ ftest.write(text)
+ apply(data_path, output, "blank:en", "text", 1, 1)
+ # Check whether it worked
+ result = list(DocBin().from_disk(output).get_docs(nlp.vocab))
+ assert len(result) == 3
+ for doc in result:
+ assert doc.text == text
+
+
+def test_applycli_user_data():
+ Doc.set_extension("ext", default=0)
+ val = ("ext", 0)
+ with make_tempdir() as data_path:
+ output = data_path / "testout.spacy"
+ nlp = spacy.blank("en")
+ doc = nlp("testing apply cli.")
+ doc._.ext = val
+ docbin = DocBin(store_user_data=True)
+ docbin.add(doc)
+ docbin.to_disk(data_path / "testin.spacy")
+ apply(data_path, output, "blank:en", "", 1, 1)
+ result = list(DocBin().from_disk(output).get_docs(nlp.vocab))
+ assert result[0]._.ext == val
+
+
+def test_local_remote_storage():
+ with make_tempdir() as d:
+ filename = "a.txt"
+
+ content_hashes = ("aaaa", "cccc", "bbbb")
+ for i, content_hash in enumerate(content_hashes):
+ # make sure that each subsequent file has a later timestamp
+ if i > 0:
+ time.sleep(1)
+ content = f"{content_hash} content"
+ loc_file = d / "root" / filename
+ if not loc_file.parent.exists():
+ loc_file.parent.mkdir(parents=True)
+ with loc_file.open(mode="w") as file_:
+ file_.write(content)
+
+ # push first version to remote storage
+ remote = RemoteStorage(d / "root", str(d / "remote"))
+ remote.push(filename, "aaaa", content_hash)
+
+ # retrieve with full hashes
+ loc_file.unlink()
+ remote.pull(filename, command_hash="aaaa", content_hash=content_hash)
+ with loc_file.open(mode="r") as file_:
+ assert file_.read() == content
+
+ # retrieve with command hash
+ loc_file.unlink()
+ remote.pull(filename, command_hash="aaaa")
+ with loc_file.open(mode="r") as file_:
+ assert file_.read() == content
+
+ # retrieve with content hash
+ loc_file.unlink()
+ remote.pull(filename, content_hash=content_hash)
+ with loc_file.open(mode="r") as file_:
+ assert file_.read() == content
+
+ # retrieve with no hashes
+ loc_file.unlink()
+ remote.pull(filename)
+ with loc_file.open(mode="r") as file_:
+ assert file_.read() == content
+
+
+def test_local_remote_storage_pull_missing():
+ # pulling from a non-existent remote pulls nothing gracefully
+ with make_tempdir() as d:
+ filename = "a.txt"
+ remote = RemoteStorage(d / "root", str(d / "remote"))
+ assert remote.pull(filename, command_hash="aaaa") is None
+ assert remote.pull(filename) is None
+
+
+def test_cli_find_threshold(capsys):
+ thresholds = numpy.linspace(0, 1, 10)
+
+ def make_examples(nlp: Language) -> List[Example]:
+ docs: List[Example] = []
+
+ for t in [
+ (
+ "I am angry and confused in the Bank of America.",
+ {
+ "cats": {"ANGRY": 1.0, "CONFUSED": 1.0, "HAPPY": 0.0},
+ "spans": {"sc": [(31, 46, "ORG")]},
+ },
+ ),
+ (
+ "I am confused but happy in New York.",
+ {
+ "cats": {"ANGRY": 0.0, "CONFUSED": 1.0, "HAPPY": 1.0},
+ "spans": {"sc": [(27, 35, "GPE")]},
+ },
+ ),
+ ]:
+ doc = nlp.make_doc(t[0])
+ docs.append(Example.from_dict(doc, t[1]))
+
+ return docs
+
+ def init_nlp(
+ components: Tuple[Tuple[str, Dict[str, Any]], ...] = ()
+ ) -> Tuple[Language, List[Example]]:
+ new_nlp = English()
+ new_nlp.add_pipe( # type: ignore
+ factory_name="textcat_multilabel",
+ name="tc_multi",
+ config={"threshold": 0.9},
+ )
+
+ # Append additional components to pipeline.
+ for cfn, comp_config in components:
+ new_nlp.add_pipe(cfn, config=comp_config)
+
+ new_examples = make_examples(new_nlp)
+ new_nlp.initialize(get_examples=lambda: new_examples)
+ for i in range(5):
+ new_nlp.update(new_examples)
+
+ return new_nlp, new_examples
+
+ with make_tempdir() as docs_dir:
+ # Check whether find_threshold() identifies lowest threshold above 0 as (first) ideal threshold, as this matches
+ # the current model behavior with the examples above. This can break once the model behavior changes and serves
+ # mostly as a smoke test.
+ nlp, examples = init_nlp()
+ DocBin(docs=[example.reference for example in examples]).to_disk(
+ docs_dir / "docs.spacy"
+ )
+ with make_tempdir() as nlp_dir:
+ nlp.to_disk(nlp_dir)
+ res = find_threshold(
+ model=nlp_dir,
+ data_path=docs_dir / "docs.spacy",
+ pipe_name="tc_multi",
+ threshold_key="threshold",
+ scores_key="cats_macro_f",
+ silent=True,
+ )
+ assert res[0] != thresholds[0]
+ assert thresholds[0] < res[0] < thresholds[9]
+ assert res[1] == 1.0
+ assert res[2][1.0] == 0.0
+
+ # Test with spancat.
+ nlp, _ = init_nlp((("spancat", {}),))
+ with make_tempdir() as nlp_dir:
+ nlp.to_disk(nlp_dir)
+ res = find_threshold(
+ model=nlp_dir,
+ data_path=docs_dir / "docs.spacy",
+ pipe_name="spancat",
+ threshold_key="threshold",
+ scores_key="spans_sc_f",
+ silent=True,
+ )
+ assert res[0] != thresholds[0]
+ assert thresholds[0] < res[0] < thresholds[8]
+ assert res[1] >= 0.6
+ assert res[2][1.0] == 0.0
+
+ # Having multiple textcat_multilabel components should work, since the name has to be specified.
+ nlp, _ = init_nlp((("textcat_multilabel", {}),))
+ with make_tempdir() as nlp_dir:
+ nlp.to_disk(nlp_dir)
+ assert find_threshold(
+ model=nlp_dir,
+ data_path=docs_dir / "docs.spacy",
+ pipe_name="tc_multi",
+ threshold_key="threshold",
+ scores_key="cats_macro_f",
+ silent=True,
+ )
+
+ # Specifying the name of an non-existing pipe should fail.
+ nlp, _ = init_nlp()
+ with make_tempdir() as nlp_dir:
+ nlp.to_disk(nlp_dir)
+ with pytest.raises(AttributeError):
+ find_threshold(
+ model=nlp_dir,
+ data_path=docs_dir / "docs.spacy",
+ pipe_name="_",
+ threshold_key="threshold",
+ scores_key="cats_macro_f",
+ silent=True,
+ )
+
+
+@pytest.mark.parametrize(
+ "reqs,output",
+ [
+ [
+ """
+ spacy
+
+ # comment
+
+ thinc""",
+ (False, False),
+ ],
+ [
+ """# comment
+ --some-flag
+ spacy""",
+ (False, False),
+ ],
+ [
+ """# comment
+ --some-flag
+ spacy; python_version >= '3.6'""",
+ (False, False),
+ ],
+ [
+ """# comment
+ spacyunknowndoesnotexist12345""",
+ (True, False),
+ ],
+ ],
+)
+def test_project_check_requirements(reqs, output):
+ # excessive guard against unlikely package name
+ try:
+ pkg_resources.require("spacyunknowndoesnotexist12345")
+ except pkg_resources.DistributionNotFound:
+ assert output == _check_requirements([req.strip() for req in reqs.split("\n")])
+
+
+def test_upload_download_local_file():
+ with make_tempdir() as d1, make_tempdir() as d2:
+ filename = "f.txt"
+ content = "content"
+ local_file = d1 / filename
+ remote_file = d2 / filename
+ with local_file.open(mode="w") as file_:
+ file_.write(content)
+ upload_file(local_file, remote_file)
+ local_file.unlink()
+ download_file(remote_file, local_file)
+ with local_file.open(mode="r") as file_:
+ assert file_.read() == content
+
+
+def test_walk_directory():
+ with make_tempdir() as d:
+ files = [
+ "data1.iob",
+ "data2.iob",
+ "data3.json",
+ "data4.conll",
+ "data5.conll",
+ "data6.conll",
+ "data7.txt",
+ ]
+
+ for f in files:
+ Path(d / f).touch()
+
+ assert (len(walk_directory(d))) == 7
+ assert (len(walk_directory(d, suffix=None))) == 7
+ assert (len(walk_directory(d, suffix="json"))) == 1
+ assert (len(walk_directory(d, suffix="iob"))) == 2
+ assert (len(walk_directory(d, suffix="conll"))) == 3
+ assert (len(walk_directory(d, suffix="pdf"))) == 0
diff --git a/spacy/tests/test_cli_app.py b/spacy/tests/test_cli_app.py
new file mode 100644
index 000000000..84b2b8d4d
--- /dev/null
+++ b/spacy/tests/test_cli_app.py
@@ -0,0 +1,42 @@
+import os
+from pathlib import Path
+from typer.testing import CliRunner
+
+from spacy.cli._util import app
+from .util import make_tempdir
+
+
+def test_convert_auto():
+ with make_tempdir() as d_in, make_tempdir() as d_out:
+ for f in ["data1.iob", "data2.iob", "data3.iob"]:
+ Path(d_in / f).touch()
+
+ # ensure that "automatic" suffix detection works
+ result = CliRunner().invoke(app, ["convert", str(d_in), str(d_out)])
+ assert "Generated output file" in result.stdout
+ out_files = os.listdir(d_out)
+ assert len(out_files) == 3
+ assert "data1.spacy" in out_files
+ assert "data2.spacy" in out_files
+ assert "data3.spacy" in out_files
+
+
+def test_convert_auto_conflict():
+ with make_tempdir() as d_in, make_tempdir() as d_out:
+ for f in ["data1.iob", "data2.iob", "data3.json"]:
+ Path(d_in / f).touch()
+
+ # ensure that "automatic" suffix detection warns when there are different file types
+ result = CliRunner().invoke(app, ["convert", str(d_in), str(d_out)])
+ assert "All input files must be same type" in result.stdout
+ out_files = os.listdir(d_out)
+ assert len(out_files) == 0
+
+
+def test_benchmark_accuracy_alias():
+ # Verify that the `evaluate` alias works correctly.
+ result_benchmark = CliRunner().invoke(app, ["benchmark", "accuracy", "--help"])
+ result_evaluate = CliRunner().invoke(app, ["evaluate", "--help"])
+ assert result_benchmark.stdout == result_evaluate.stdout.replace(
+ "spacy evaluate", "spacy benchmark accuracy"
+ )
diff --git a/spacy/tests/test_displacy.py b/spacy/tests/test_displacy.py
index 392c95e42..f298b38e0 100644
--- a/spacy/tests/test_displacy.py
+++ b/spacy/tests/test_displacy.py
@@ -83,6 +83,27 @@ def test_issue3882(en_vocab):
displacy.parse_deps(doc)
+@pytest.mark.issue(5447)
+def test_issue5447():
+ """Test that overlapping arcs get separate levels, unless they're identical."""
+ renderer = DependencyRenderer()
+ words = [
+ {"text": "This", "tag": "DT"},
+ {"text": "is", "tag": "VBZ"},
+ {"text": "a", "tag": "DT"},
+ {"text": "sentence.", "tag": "NN"},
+ ]
+ arcs = [
+ {"start": 0, "end": 1, "label": "nsubj", "dir": "left"},
+ {"start": 2, "end": 3, "label": "det", "dir": "left"},
+ {"start": 2, "end": 3, "label": "overlap", "dir": "left"},
+ {"end": 3, "label": "overlap", "start": 2, "dir": "left"},
+ {"start": 1, "end": 3, "label": "attr", "dir": "left"},
+ ]
+ renderer.render([{"words": words, "arcs": arcs}])
+ assert renderer.highest_level == 3
+
+
@pytest.mark.issue(5838)
def test_issue5838():
# Displacy's EntityRenderer break line
@@ -96,6 +117,102 @@ def test_issue5838():
assert found == 4
+def test_displacy_parse_spans(en_vocab):
+ """Test that spans on a Doc are converted into displaCy's format."""
+ doc = Doc(en_vocab, words=["Welcome", "to", "the", "Bank", "of", "China"])
+ doc.spans["sc"] = [Span(doc, 3, 6, "ORG"), Span(doc, 5, 6, "GPE")]
+ spans = displacy.parse_spans(doc)
+ assert isinstance(spans, dict)
+ assert spans["text"] == "Welcome to the Bank of China "
+ assert spans["spans"] == [
+ {
+ "start": 15,
+ "end": 28,
+ "start_token": 3,
+ "end_token": 6,
+ "label": "ORG",
+ "kb_id": "",
+ "kb_url": "#",
+ },
+ {
+ "start": 23,
+ "end": 28,
+ "start_token": 5,
+ "end_token": 6,
+ "label": "GPE",
+ "kb_id": "",
+ "kb_url": "#",
+ },
+ ]
+
+
+def test_displacy_parse_spans_with_kb_id_options(en_vocab):
+ """Test that spans with kb_id on a Doc are converted into displaCy's format"""
+ doc = Doc(en_vocab, words=["Welcome", "to", "the", "Bank", "of", "China"])
+ doc.spans["sc"] = [
+ Span(doc, 3, 6, "ORG", kb_id="Q790068"),
+ Span(doc, 5, 6, "GPE", kb_id="Q148"),
+ ]
+
+ spans = displacy.parse_spans(
+ doc, {"kb_url_template": "https://wikidata.org/wiki/{}"}
+ )
+ assert isinstance(spans, dict)
+ assert spans["text"] == "Welcome to the Bank of China "
+ assert spans["spans"] == [
+ {
+ "start": 15,
+ "end": 28,
+ "start_token": 3,
+ "end_token": 6,
+ "label": "ORG",
+ "kb_id": "Q790068",
+ "kb_url": "https://wikidata.org/wiki/Q790068",
+ },
+ {
+ "start": 23,
+ "end": 28,
+ "start_token": 5,
+ "end_token": 6,
+ "label": "GPE",
+ "kb_id": "Q148",
+ "kb_url": "https://wikidata.org/wiki/Q148",
+ },
+ ]
+
+
+def test_displacy_parse_spans_different_spans_key(en_vocab):
+ """Test that spans in a different spans key will be parsed"""
+ doc = Doc(en_vocab, words=["Welcome", "to", "the", "Bank", "of", "China"])
+ doc.spans["sc"] = [Span(doc, 3, 6, "ORG"), Span(doc, 5, 6, "GPE")]
+ doc.spans["custom"] = [Span(doc, 3, 6, "BANK")]
+ spans = displacy.parse_spans(doc, options={"spans_key": "custom"})
+
+ assert isinstance(spans, dict)
+ assert spans["text"] == "Welcome to the Bank of China "
+ assert spans["spans"] == [
+ {
+ "start": 15,
+ "end": 28,
+ "start_token": 3,
+ "end_token": 6,
+ "label": "BANK",
+ "kb_id": "",
+ "kb_url": "#",
+ }
+ ]
+
+
+def test_displacy_parse_empty_spans_key(en_vocab):
+ """Test that having an unset spans key doesn't raise an error"""
+ doc = Doc(en_vocab, words=["Welcome", "to", "the", "Bank", "of", "China"])
+ doc.spans["custom"] = [Span(doc, 3, 6, "BANK")]
+ with pytest.warns(UserWarning, match="W117"):
+ spans = displacy.parse_spans(doc)
+
+ assert isinstance(spans, dict)
+
+
def test_displacy_parse_ents(en_vocab):
"""Test that named entities on a Doc are converted into displaCy's format."""
doc = Doc(en_vocab, words=["But", "Google", "is", "starting", "from", "behind"])
@@ -231,3 +348,18 @@ def test_displacy_options_case():
assert "green" in result[1] and "bar" in result[1]
assert "red" in result[2] and "FOO" in result[2]
assert "green" in result[3] and "BAR" in result[3]
+
+
+@pytest.mark.issue(10672)
+def test_displacy_manual_sorted_entities():
+ doc = {
+ "text": "But Google is starting from behind.",
+ "ents": [
+ {"start": 14, "end": 22, "label": "SECOND"},
+ {"start": 4, "end": 10, "label": "FIRST"},
+ ],
+ "title": None,
+ }
+
+ html = displacy.render(doc, style="ent", manual=True)
+ assert html.find("FIRST") < html.find("SECOND")
diff --git a/spacy/tests/test_language.py b/spacy/tests/test_language.py
index c5fdc8eb0..03790eb86 100644
--- a/spacy/tests/test_language.py
+++ b/spacy/tests/test_language.py
@@ -3,6 +3,7 @@ import logging
from unittest import mock
import pytest
from spacy.language import Language
+from spacy.scorer import Scorer
from spacy.tokens import Doc, Span
from spacy.vocab import Vocab
from spacy.training import Example
@@ -126,6 +127,112 @@ def test_evaluate_no_pipe(nlp):
nlp.evaluate([Example.from_dict(doc, annots)])
+def test_evaluate_textcat_multilabel(en_vocab):
+ """Test that evaluate works with a multilabel textcat pipe."""
+ nlp = Language(en_vocab)
+ textcat_multilabel = nlp.add_pipe("textcat_multilabel")
+ for label in ("FEATURE", "REQUEST", "BUG", "QUESTION"):
+ textcat_multilabel.add_label(label)
+ nlp.initialize()
+
+ annots = {"cats": {"FEATURE": 1.0, "QUESTION": 1.0}}
+ doc = nlp.make_doc("hello world")
+ example = Example.from_dict(doc, annots)
+ scores = nlp.evaluate([example])
+ labels = nlp.get_pipe("textcat_multilabel").labels
+ for label in labels:
+ assert scores["cats_f_per_type"].get(label) is not None
+ for key in example.reference.cats.keys():
+ if key not in labels:
+ assert scores["cats_f_per_type"].get(key) is None
+
+
+def test_evaluate_multiple_textcat_final(en_vocab):
+ """Test that evaluate evaluates the final textcat component in a pipeline
+ with more than one textcat or textcat_multilabel."""
+ nlp = Language(en_vocab)
+ textcat = nlp.add_pipe("textcat")
+ for label in ("POSITIVE", "NEGATIVE"):
+ textcat.add_label(label)
+ textcat_multilabel = nlp.add_pipe("textcat_multilabel")
+ for label in ("FEATURE", "REQUEST", "BUG", "QUESTION"):
+ textcat_multilabel.add_label(label)
+ nlp.initialize()
+
+ annots = {
+ "cats": {
+ "POSITIVE": 1.0,
+ "NEGATIVE": 0.0,
+ "FEATURE": 1.0,
+ "QUESTION": 1.0,
+ "POSITIVE": 1.0,
+ "NEGATIVE": 0.0,
+ }
+ }
+ doc = nlp.make_doc("hello world")
+ example = Example.from_dict(doc, annots)
+ scores = nlp.evaluate([example])
+ # get the labels from the final pipe
+ labels = nlp.get_pipe(nlp.pipe_names[-1]).labels
+ for label in labels:
+ assert scores["cats_f_per_type"].get(label) is not None
+ for key in example.reference.cats.keys():
+ if key not in labels:
+ assert scores["cats_f_per_type"].get(key) is None
+
+
+def test_evaluate_multiple_textcat_separate(en_vocab):
+ """Test that evaluate can evaluate multiple textcat components separately
+ with custom scorers."""
+
+ def custom_textcat_score(examples, **kwargs):
+ scores = Scorer.score_cats(
+ examples,
+ "cats",
+ multi_label=False,
+ **kwargs,
+ )
+ return {f"custom_{k}": v for k, v in scores.items()}
+
+ @spacy.registry.scorers("test_custom_textcat_scorer")
+ def make_custom_textcat_scorer():
+ return custom_textcat_score
+
+ nlp = Language(en_vocab)
+ textcat = nlp.add_pipe(
+ "textcat",
+ config={"scorer": {"@scorers": "test_custom_textcat_scorer"}},
+ )
+ for label in ("POSITIVE", "NEGATIVE"):
+ textcat.add_label(label)
+ textcat_multilabel = nlp.add_pipe("textcat_multilabel")
+ for label in ("FEATURE", "REQUEST", "BUG", "QUESTION"):
+ textcat_multilabel.add_label(label)
+ nlp.initialize()
+
+ annots = {
+ "cats": {
+ "POSITIVE": 1.0,
+ "NEGATIVE": 0.0,
+ "FEATURE": 1.0,
+ "QUESTION": 1.0,
+ "POSITIVE": 1.0,
+ "NEGATIVE": 0.0,
+ }
+ }
+ doc = nlp.make_doc("hello world")
+ example = Example.from_dict(doc, annots)
+ scores = nlp.evaluate([example])
+ # check custom scores for the textcat pipe
+ assert "custom_cats_f_per_type" in scores
+ labels = nlp.get_pipe("textcat").labels
+ assert set(scores["custom_cats_f_per_type"].keys()) == set(labels)
+ # check default scores for the textcat_multilabel pipe
+ assert "cats_f_per_type" in scores
+ labels = nlp.get_pipe("textcat_multilabel").labels
+ assert set(scores["cats_f_per_type"].keys()) == set(labels)
+
+
def vector_modification_pipe(doc):
doc.vector += 1
return doc
@@ -659,3 +766,36 @@ def test_multiprocessing_gpu_warning(nlp2, texts):
# Trigger multi-processing.
for _ in docs:
pass
+
+
+def test_dot_in_factory_names(nlp):
+ Language.component("my_evil_component", func=evil_component)
+ nlp.add_pipe("my_evil_component")
+
+ with pytest.raises(ValueError, match="not permitted"):
+ Language.component("my.evil.component.v1", func=evil_component)
+
+ with pytest.raises(ValueError, match="not permitted"):
+ Language.factory("my.evil.component.v1", func=evil_component)
+
+
+def test_component_return():
+ """Test that an error is raised if components return a type other than a
+ doc."""
+ nlp = English()
+
+ @Language.component("test_component_good_pipe")
+ def good_pipe(doc):
+ return doc
+
+ nlp.add_pipe("test_component_good_pipe")
+ nlp("text")
+ nlp.remove_pipe("test_component_good_pipe")
+
+ @Language.component("test_component_bad_pipe")
+ def bad_pipe(doc):
+ return doc.text
+
+ nlp.add_pipe("test_component_bad_pipe")
+ with pytest.raises(ValueError, match="instead of a Doc"):
+ nlp("text")
diff --git a/spacy/tests/test_misc.py b/spacy/tests/test_misc.py
index d8743d322..618f17334 100644
--- a/spacy/tests/test_misc.py
+++ b/spacy/tests/test_misc.py
@@ -8,9 +8,10 @@ from spacy import prefer_gpu, require_gpu, require_cpu
from spacy.ml._precomputable_affine import PrecomputableAffine
from spacy.ml._precomputable_affine import _backprop_precomputable_affine_padding
from spacy.util import dot_to_object, SimpleFrozenList, import_file
-from spacy.util import to_ternary_int
+from spacy.util import to_ternary_int, find_available_port
from thinc.api import Config, Optimizer, ConfigValidationError
-from thinc.api import set_current_ops
+from thinc.api import get_current_ops, set_current_ops, NumpyOps, CupyOps, MPSOps
+from thinc.compat import has_cupy_gpu, has_torch_mps_gpu
from spacy.training.batchers import minibatch_by_words
from spacy.lang.en import English
from spacy.lang.nl import Dutch
@@ -18,7 +19,6 @@ from spacy.language import DEFAULT_CONFIG_PATH
from spacy.schemas import ConfigSchemaTraining, TokenPattern, TokenPatternSchema
from pydantic import ValidationError
-from thinc.api import get_current_ops, NumpyOps, CupyOps
from .util import get_random_doc, make_tempdir
@@ -111,26 +111,25 @@ def test_PrecomputableAffine(nO=4, nI=5, nF=3, nP=2):
def test_prefer_gpu():
current_ops = get_current_ops()
- try:
- import cupy # noqa: F401
-
- prefer_gpu()
+ if has_cupy_gpu:
+ assert prefer_gpu()
assert isinstance(get_current_ops(), CupyOps)
- except ImportError:
+ elif has_torch_mps_gpu:
+ assert prefer_gpu()
+ assert isinstance(get_current_ops(), MPSOps)
+ else:
assert not prefer_gpu()
set_current_ops(current_ops)
def test_require_gpu():
current_ops = get_current_ops()
- try:
- import cupy # noqa: F401
-
+ if has_cupy_gpu:
require_gpu()
assert isinstance(get_current_ops(), CupyOps)
- except ImportError:
- with pytest.raises(ValueError):
- require_gpu()
+ elif has_torch_mps_gpu:
+ require_gpu()
+ assert isinstance(get_current_ops(), MPSOps)
set_current_ops(current_ops)
@@ -435,3 +434,16 @@ def test_to_ternary_int():
assert to_ternary_int(-10) == -1
assert to_ternary_int("string") == -1
assert to_ternary_int([0, "string"]) == -1
+
+
+def test_find_available_port():
+ host = "0.0.0.0"
+ port = 5000
+ assert find_available_port(port, host) == port, "Port 5000 isn't free"
+
+ from wsgiref.simple_server import make_server, demo_app
+
+ with make_server(host, port, demo_app) as httpd:
+ with pytest.warns(UserWarning, match="already in use"):
+ found_port = find_available_port(port, host, auto_select=True)
+ assert found_port == port + 1, "Didn't find next port"
diff --git a/spacy/tests/test_models.py b/spacy/tests/test_models.py
index 2306cabb7..d91ed1201 100644
--- a/spacy/tests/test_models.py
+++ b/spacy/tests/test_models.py
@@ -23,7 +23,7 @@ def get_textcat_bow_kwargs():
def get_textcat_cnn_kwargs():
- return {"tok2vec": test_tok2vec(), "exclusive_classes": False, "nO": 13}
+ return {"tok2vec": make_test_tok2vec(), "exclusive_classes": False, "nO": 13}
def get_all_params(model):
@@ -65,7 +65,7 @@ def get_tok2vec_kwargs():
}
-def test_tok2vec():
+def make_test_tok2vec():
return build_Tok2Vec_model(**get_tok2vec_kwargs())
diff --git a/spacy/tests/test_scorer.py b/spacy/tests/test_scorer.py
index cdc706ebd..385d99b57 100644
--- a/spacy/tests/test_scorer.py
+++ b/spacy/tests/test_scorer.py
@@ -58,7 +58,7 @@ def test_tokenization(sented_doc):
)
example.predicted[1].is_sent_start = False
scores = scorer.score([example])
- assert scores["token_acc"] == approx(0.66666666)
+ assert scores["token_acc"] == 0.5
assert scores["token_p"] == 0.5
assert scores["token_r"] == approx(0.33333333)
assert scores["token_f"] == 0.4
@@ -422,3 +422,50 @@ def test_prf_score():
assert (a.precision, a.recall, a.fscore) == approx(
(c.precision, c.recall, c.fscore)
)
+
+
+def test_score_cats(en_tokenizer):
+ text = "some text"
+ gold_doc = en_tokenizer(text)
+ gold_doc.cats = {"POSITIVE": 1.0, "NEGATIVE": 0.0}
+ pred_doc = en_tokenizer(text)
+ pred_doc.cats = {"POSITIVE": 0.75, "NEGATIVE": 0.25}
+ example = Example(pred_doc, gold_doc)
+ # threshold is ignored for multi_label=False
+ scores1 = Scorer.score_cats(
+ [example],
+ "cats",
+ labels=list(gold_doc.cats.keys()),
+ multi_label=False,
+ positive_label="POSITIVE",
+ threshold=0.1,
+ )
+ scores2 = Scorer.score_cats(
+ [example],
+ "cats",
+ labels=list(gold_doc.cats.keys()),
+ multi_label=False,
+ positive_label="POSITIVE",
+ threshold=0.9,
+ )
+ assert scores1["cats_score"] == 1.0
+ assert scores2["cats_score"] == 1.0
+ assert scores1 == scores2
+ # threshold is relevant for multi_label=True
+ scores = Scorer.score_cats(
+ [example],
+ "cats",
+ labels=list(gold_doc.cats.keys()),
+ multi_label=True,
+ threshold=0.9,
+ )
+ assert scores["cats_macro_f"] == 0.0
+ # threshold is relevant for multi_label=True
+ scores = Scorer.score_cats(
+ [example],
+ "cats",
+ labels=list(gold_doc.cats.keys()),
+ multi_label=True,
+ threshold=0.1,
+ )
+ assert scores["cats_macro_f"] == 0.5
diff --git a/spacy/tests/tokenizer/test_explain.py b/spacy/tests/tokenizer/test_explain.py
index 0a10ae67d..5b4eeca16 100644
--- a/spacy/tests/tokenizer/test_explain.py
+++ b/spacy/tests/tokenizer/test_explain.py
@@ -1,7 +1,13 @@
-import pytest
import re
-from spacy.util import get_lang_class
+import string
+
+import hypothesis
+import hypothesis.strategies
+import pytest
+
+import spacy
from spacy.tokenizer import Tokenizer
+from spacy.util import get_lang_class
# Only include languages with no external dependencies
# "is" seems to confuse importlib, so we're also excluding it for now
@@ -77,3 +83,46 @@ def test_tokenizer_explain_special_matcher(en_vocab):
tokens = [t.text for t in tokenizer("a/a.")]
explain_tokens = [t[1] for t in tokenizer.explain("a/a.")]
assert tokens == explain_tokens
+
+
+@hypothesis.strategies.composite
+def sentence_strategy(draw: hypothesis.strategies.DrawFn, max_n_words: int = 4) -> str:
+ """
+ Composite strategy for fuzzily generating sentence with varying interpunctation.
+
+ draw (hypothesis.strategies.DrawFn): Protocol for drawing function allowing to fuzzily pick from hypothesis'
+ strategies.
+ max_n_words (int): Max. number of words in generated sentence.
+ RETURNS (str): Fuzzily generated sentence.
+ """
+
+ punctuation_and_space_regex = "|".join(
+ [*[re.escape(p) for p in string.punctuation], r"\s"]
+ )
+ sentence = [
+ [
+ draw(hypothesis.strategies.text(min_size=1)),
+ draw(hypothesis.strategies.from_regex(punctuation_and_space_regex)),
+ ]
+ for _ in range(
+ draw(hypothesis.strategies.integers(min_value=2, max_value=max_n_words))
+ )
+ ]
+
+ return " ".join([token for token_pair in sentence for token in token_pair])
+
+
+@pytest.mark.xfail
+@pytest.mark.parametrize("lang", LANGUAGES)
+@hypothesis.given(sentence=sentence_strategy())
+def test_tokenizer_explain_fuzzy(lang: str, sentence: str) -> None:
+ """
+ Tests whether output of tokenizer.explain() matches tokenizer output. Input generated by hypothesis.
+ lang (str): Language to test.
+ text (str): Fuzzily generated sentence to tokenize.
+ """
+
+ tokenizer: Tokenizer = spacy.blank(lang).tokenizer
+ tokens = [t.text for t in tokenizer(sentence) if not t.is_space]
+ debug_tokens = [t[1] for t in tokenizer.explain(sentence)]
+ assert tokens == debug_tokens, f"{tokens}, {debug_tokens}, {sentence}"
diff --git a/spacy/tests/tokenizer/test_tokenizer.py b/spacy/tests/tokenizer/test_tokenizer.py
index a7270cb1e..6af58b344 100644
--- a/spacy/tests/tokenizer/test_tokenizer.py
+++ b/spacy/tests/tokenizer/test_tokenizer.py
@@ -521,3 +521,33 @@ def test_tokenizer_infix_prefix(en_vocab):
assert tokens == ["±10", "%"]
explain_tokens = [t[1] for t in tokenizer.explain("±10%")]
assert tokens == explain_tokens
+
+
+@pytest.mark.issue(10086)
+def test_issue10086(en_tokenizer):
+ """Test special case works when part of infix substring."""
+ text = "No--don't see"
+
+ # without heuristics: do n't
+ en_tokenizer.faster_heuristics = False
+ doc = en_tokenizer(text)
+ assert "n't" in [w.text for w in doc]
+ assert "do" in [w.text for w in doc]
+
+ # with (default) heuristics: don't
+ en_tokenizer.faster_heuristics = True
+ doc = en_tokenizer(text)
+ assert "don't" in [w.text for w in doc]
+
+
+def test_tokenizer_initial_special_case_explain(en_vocab):
+ tokenizer = Tokenizer(
+ en_vocab,
+ token_match=re.compile("^id$").match,
+ rules={
+ "id": [{"ORTH": "i"}, {"ORTH": "d"}],
+ },
+ )
+ tokens = [t.text for t in tokenizer("id")]
+ explain_tokens = [t[1] for t in tokenizer.explain("id")]
+ assert tokens == explain_tokens
diff --git a/spacy/tests/training/test_augmenters.py b/spacy/tests/training/test_augmenters.py
index e3639c5da..35860a199 100644
--- a/spacy/tests/training/test_augmenters.py
+++ b/spacy/tests/training/test_augmenters.py
@@ -31,7 +31,7 @@ def doc(nlp):
words = ["Sarah", "'s", "sister", "flew", "to", "Silicon", "Valley", "via", "London", "."]
tags = ["NNP", "POS", "NN", "VBD", "IN", "NNP", "NNP", "IN", "NNP", "."]
pos = ["PROPN", "PART", "NOUN", "VERB", "ADP", "PROPN", "PROPN", "ADP", "PROPN", "PUNCT"]
- ents = ["B-PERSON", "I-PERSON", "O", "O", "O", "B-LOC", "I-LOC", "O", "B-GPE", "O"]
+ ents = ["B-PERSON", "I-PERSON", "O", "", "O", "B-LOC", "I-LOC", "O", "B-GPE", "O"]
cats = {"TRAVEL": 1.0, "BAKING": 0.0}
# fmt: on
doc = Doc(nlp.vocab, words=words, tags=tags, pos=pos, ents=ents)
@@ -106,6 +106,7 @@ def test_lowercase_augmenter(nlp, doc):
assert [(e.start, e.end, e.label) for e in eg.reference.ents] == ents
for ref_ent, orig_ent in zip(eg.reference.ents, doc.ents):
assert ref_ent.text == orig_ent.text.lower()
+ assert [t.ent_iob for t in doc] == [t.ent_iob for t in eg.reference]
assert [t.pos_ for t in eg.reference] == [t.pos_ for t in doc]
# check that augmentation works when lowercasing leads to different
@@ -166,7 +167,7 @@ def test_make_whitespace_variant(nlp):
lemmas = ["they", "fly", "to", "New", "York", "City", ".", "\n", "then", "they", "drive", "to", "Washington", ",", "D.C."]
heads = [1, 1, 1, 4, 5, 2, 1, 10, 10, 10, 10, 10, 11, 12, 12]
deps = ["nsubj", "ROOT", "prep", "compound", "compound", "pobj", "punct", "dep", "advmod", "nsubj", "ROOT", "prep", "pobj", "punct", "appos"]
- ents = ["O", "O", "O", "B-GPE", "I-GPE", "I-GPE", "O", "O", "O", "O", "O", "O", "B-GPE", "O", "B-GPE"]
+ ents = ["O", "", "O", "B-GPE", "I-GPE", "I-GPE", "O", "O", "O", "O", "O", "O", "B-GPE", "O", "B-GPE"]
# fmt: on
doc = Doc(
nlp.vocab,
@@ -215,6 +216,8 @@ def test_make_whitespace_variant(nlp):
assert mod_ex2.reference[j].head.i == j - 1
# entities are well-formed
assert len(doc.ents) == len(mod_ex.reference.ents)
+ # there is one token with missing entity information
+ assert any(t.ent_iob == 0 for t in mod_ex.reference)
for ent in mod_ex.reference.ents:
assert not ent[0].is_space
assert not ent[-1].is_space
diff --git a/spacy/tests/training/test_logger.py b/spacy/tests/training/test_logger.py
new file mode 100644
index 000000000..0dfd0cbf4
--- /dev/null
+++ b/spacy/tests/training/test_logger.py
@@ -0,0 +1,30 @@
+import pytest
+import spacy
+
+from spacy.training import loggers
+
+
+@pytest.fixture()
+def nlp():
+ nlp = spacy.blank("en")
+ nlp.add_pipe("ner")
+ return nlp
+
+
+@pytest.fixture()
+def info():
+ return {
+ "losses": {"ner": 100},
+ "other_scores": {"ENTS_F": 0.85, "ENTS_P": 0.90, "ENTS_R": 0.80},
+ "epoch": 100,
+ "step": 125,
+ "score": 85,
+ }
+
+
+def test_console_logger(nlp, info):
+ console_logger = loggers.console_logger(
+ progress_bar=True, console_output=True, output_file=None
+ )
+ log_step, finalize = console_logger(nlp)
+ log_step(info)
diff --git a/spacy/tests/training/test_new_example.py b/spacy/tests/training/test_new_example.py
index a39d40ded..6b15603b3 100644
--- a/spacy/tests/training/test_new_example.py
+++ b/spacy/tests/training/test_new_example.py
@@ -431,3 +431,41 @@ def test_Example_aligned_whitespace(en_vocab):
example = Example(predicted, reference)
assert example.get_aligned("TAG", as_string=True) == tags
+
+
+@pytest.mark.issue("11260")
+def test_issue11260():
+ annots = {
+ "words": ["I", "like", "New", "York", "."],
+ "spans": {
+ "cities": [(7, 15, "LOC", "")],
+ "people": [(0, 1, "PERSON", "")],
+ },
+ }
+ vocab = Vocab()
+ predicted = Doc(vocab, words=annots["words"])
+ example = Example.from_dict(predicted, annots)
+ assert len(example.reference.spans["cities"]) == 1
+ assert len(example.reference.spans["people"]) == 1
+
+ output_dict = example.to_dict()
+ assert "spans" in output_dict["doc_annotation"]
+ assert output_dict["doc_annotation"]["spans"]["cities"] == annots["spans"]["cities"]
+ assert output_dict["doc_annotation"]["spans"]["people"] == annots["spans"]["people"]
+
+ output_example = Example.from_dict(predicted, output_dict)
+
+ assert len(output_example.reference.spans["cities"]) == len(
+ example.reference.spans["cities"]
+ )
+ assert len(output_example.reference.spans["people"]) == len(
+ example.reference.spans["people"]
+ )
+ for span in example.reference.spans["cities"]:
+ assert span.label_ == "LOC"
+ assert span.text == "New York"
+ assert span.start_char == 7
+ for span in example.reference.spans["people"]:
+ assert span.label_ == "PERSON"
+ assert span.text == "I"
+ assert span.start_char == 0
diff --git a/spacy/tests/training/test_pretraining.py b/spacy/tests/training/test_pretraining.py
index 8ee54b544..9359c8485 100644
--- a/spacy/tests/training/test_pretraining.py
+++ b/spacy/tests/training/test_pretraining.py
@@ -38,7 +38,7 @@ subword_features = true
factory = "tagger"
[components.tagger.model]
-@architectures = "spacy.Tagger.v1"
+@architectures = "spacy.Tagger.v2"
[components.tagger.model.tok2vec]
@architectures = "spacy.Tok2VecListener.v1"
@@ -62,7 +62,7 @@ pipeline = ["tagger"]
factory = "tagger"
[components.tagger.model]
-@architectures = "spacy.Tagger.v1"
+@architectures = "spacy.Tagger.v2"
[components.tagger.model.tok2vec]
@architectures = "spacy.HashEmbedCNN.v1"
@@ -106,7 +106,7 @@ subword_features = true
factory = "tagger"
[components.tagger.model]
-@architectures = "spacy.Tagger.v1"
+@architectures = "spacy.Tagger.v2"
[components.tagger.model.tok2vec]
@architectures = "spacy.Tok2VecListener.v1"
diff --git a/spacy/tests/training/test_rehearse.py b/spacy/tests/training/test_rehearse.py
index 84c507702..5ac7fc217 100644
--- a/spacy/tests/training/test_rehearse.py
+++ b/spacy/tests/training/test_rehearse.py
@@ -181,7 +181,7 @@ def _optimize(nlp, component: str, data: List, rehearse: bool):
elif component == "tagger":
_add_tagger_label(pipe, data)
elif component == "parser":
- _add_tagger_label(pipe, data)
+ _add_parser_label(pipe, data)
elif component == "textcat_multilabel":
_add_textcat_label(pipe, data)
else:
diff --git a/spacy/tests/training/test_training.py b/spacy/tests/training/test_training.py
index 0d73300d8..7933ea31f 100644
--- a/spacy/tests/training/test_training.py
+++ b/spacy/tests/training/test_training.py
@@ -2,17 +2,20 @@ import random
import numpy
import pytest
+import spacy
import srsly
from spacy.lang.en import English
from spacy.tokens import Doc, DocBin
from spacy.training import Alignment, Corpus, Example, biluo_tags_to_offsets
from spacy.training import biluo_tags_to_spans, docs_to_json, iob_to_biluo
from spacy.training import offsets_to_biluo_tags
+from spacy.training.alignment_array import AlignmentArray
from spacy.training.align import get_alignments
from spacy.training.converters import json_to_docs
+from spacy.training.loop import train_while_improving
from spacy.util import get_words_and_spaces, load_model_from_path, minibatch
from spacy.util import load_config_from_str
-from thinc.api import compounding
+from thinc.api import compounding, Adam
from ..util import make_tempdir
@@ -241,7 +244,7 @@ maxout_pieces = 3
factory = "tagger"
[components.tagger.model]
-@architectures = "spacy.Tagger.v1"
+@architectures = "spacy.Tagger.v2"
nO = null
[components.tagger.model.tok2vec]
@@ -670,13 +673,38 @@ def test_gold_ner_missing_tags(en_tokenizer):
def test_projectivize(en_tokenizer):
doc = en_tokenizer("He pretty quickly walks away")
- heads = [3, 2, 3, 0, 2]
+ heads = [3, 2, 3, 3, 2]
deps = ["dep"] * len(heads)
example = Example.from_dict(doc, {"heads": heads, "deps": deps})
proj_heads, proj_labels = example.get_aligned_parse(projectivize=True)
nonproj_heads, nonproj_labels = example.get_aligned_parse(projectivize=False)
- assert proj_heads == [3, 2, 3, 0, 3]
- assert nonproj_heads == [3, 2, 3, 0, 2]
+ assert proj_heads == [3, 2, 3, 3, 3]
+ assert nonproj_heads == [3, 2, 3, 3, 2]
+
+ # Test single token documents
+ doc = en_tokenizer("Conrail")
+ heads = [0]
+ deps = ["dep"]
+ example = Example.from_dict(doc, {"heads": heads, "deps": deps})
+ proj_heads, proj_labels = example.get_aligned_parse(projectivize=True)
+ assert proj_heads == heads
+ assert proj_labels == deps
+
+ # Test documents with no alignments
+ doc_a = Doc(
+ doc.vocab, words=["Double-Jointed"], spaces=[False], deps=["ROOT"], heads=[0]
+ )
+ doc_b = Doc(
+ doc.vocab,
+ words=["Double", "-", "Jointed"],
+ spaces=[True, True, True],
+ deps=["amod", "punct", "ROOT"],
+ heads=[2, 2, 2],
+ )
+ example = Example(doc_a, doc_b)
+ proj_heads, proj_deps = example.get_aligned_parse(projectivize=True)
+ assert proj_heads == [None]
+ assert proj_deps == [None]
def test_iob_to_biluo():
@@ -908,9 +936,41 @@ def test_alignment():
spacy_tokens = ["i", "listened", "to", "obama", "'s", "podcasts", "."]
align = Alignment.from_strings(other_tokens, spacy_tokens)
assert list(align.x2y.lengths) == [1, 1, 1, 1, 1, 1, 1, 1]
- assert list(align.x2y.dataXd) == [0, 1, 2, 3, 4, 4, 5, 6]
+ assert list(align.x2y.data) == [0, 1, 2, 3, 4, 4, 5, 6]
assert list(align.y2x.lengths) == [1, 1, 1, 1, 2, 1, 1]
- assert list(align.y2x.dataXd) == [0, 1, 2, 3, 4, 5, 6, 7]
+ assert list(align.y2x.data) == [0, 1, 2, 3, 4, 5, 6, 7]
+
+
+def test_alignment_array():
+ a = AlignmentArray([[0, 1, 2], [3], [], [4, 5, 6, 7], [8, 9]])
+ assert list(a.data) == [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+ assert list(a.lengths) == [3, 1, 0, 4, 2]
+ assert list(a[3]) == [4, 5, 6, 7]
+ assert list(a[2]) == []
+ assert list(a[-2]) == [4, 5, 6, 7]
+ assert list(a[1:4]) == [3, 4, 5, 6, 7]
+ assert list(a[1:]) == [3, 4, 5, 6, 7, 8, 9]
+ assert list(a[:3]) == [0, 1, 2, 3]
+ assert list(a[:]) == list(a.data)
+ assert list(a[0:0]) == []
+ assert list(a[3:3]) == []
+ assert list(a[-1:-1]) == []
+ with pytest.raises(ValueError, match=r"only supports slicing with a step of 1"):
+ a[:4:-1]
+ with pytest.raises(
+ ValueError, match=r"only supports indexing using an int or a slice"
+ ):
+ a[[0, 1, 3]]
+
+ a = AlignmentArray([[], [1, 2, 3], [4, 5]])
+ assert list(a[0]) == []
+ assert list(a[0:1]) == []
+ assert list(a[2]) == [4, 5]
+ assert list(a[0:2]) == [1, 2, 3]
+
+ a = AlignmentArray([[1, 2, 3], [4, 5], []])
+ assert list(a[-1]) == []
+ assert list(a[-2:]) == [4, 5]
def test_alignment_case_insensitive():
@@ -918,9 +978,9 @@ def test_alignment_case_insensitive():
spacy_tokens = ["i", "listened", "to", "Obama", "'s", "PODCASTS", "."]
align = Alignment.from_strings(other_tokens, spacy_tokens)
assert list(align.x2y.lengths) == [1, 1, 1, 1, 1, 1, 1, 1]
- assert list(align.x2y.dataXd) == [0, 1, 2, 3, 4, 4, 5, 6]
+ assert list(align.x2y.data) == [0, 1, 2, 3, 4, 4, 5, 6]
assert list(align.y2x.lengths) == [1, 1, 1, 1, 2, 1, 1]
- assert list(align.y2x.dataXd) == [0, 1, 2, 3, 4, 5, 6, 7]
+ assert list(align.y2x.data) == [0, 1, 2, 3, 4, 5, 6, 7]
def test_alignment_complex():
@@ -928,9 +988,9 @@ def test_alignment_complex():
spacy_tokens = ["i", "listened", "to", "obama", "'s", "podcasts."]
align = Alignment.from_strings(other_tokens, spacy_tokens)
assert list(align.x2y.lengths) == [3, 1, 1, 1, 1, 1]
- assert list(align.x2y.dataXd) == [0, 1, 2, 3, 4, 4, 5, 5]
+ assert list(align.x2y.data) == [0, 1, 2, 3, 4, 4, 5, 5]
assert list(align.y2x.lengths) == [1, 1, 1, 1, 2, 2]
- assert list(align.y2x.dataXd) == [0, 0, 0, 1, 2, 3, 4, 5]
+ assert list(align.y2x.data) == [0, 0, 0, 1, 2, 3, 4, 5]
def test_alignment_complex_example(en_vocab):
@@ -947,9 +1007,9 @@ def test_alignment_complex_example(en_vocab):
example = Example(predicted, reference)
align = example.alignment
assert list(align.x2y.lengths) == [3, 1, 1, 1, 1, 1]
- assert list(align.x2y.dataXd) == [0, 1, 2, 3, 4, 4, 5, 5]
+ assert list(align.x2y.data) == [0, 1, 2, 3, 4, 4, 5, 5]
assert list(align.y2x.lengths) == [1, 1, 1, 1, 2, 2]
- assert list(align.y2x.dataXd) == [0, 0, 0, 1, 2, 3, 4, 5]
+ assert list(align.y2x.data) == [0, 0, 0, 1, 2, 3, 4, 5]
def test_alignment_different_texts():
@@ -965,70 +1025,70 @@ def test_alignment_spaces(en_vocab):
spacy_tokens = ["i", "listened", "to", "obama", "'s", "podcasts."]
align = Alignment.from_strings(other_tokens, spacy_tokens)
assert list(align.x2y.lengths) == [0, 3, 1, 1, 1, 1, 1]
- assert list(align.x2y.dataXd) == [0, 1, 2, 3, 4, 4, 5, 5]
+ assert list(align.x2y.data) == [0, 1, 2, 3, 4, 4, 5, 5]
assert list(align.y2x.lengths) == [1, 1, 1, 1, 2, 2]
- assert list(align.y2x.dataXd) == [1, 1, 1, 2, 3, 4, 5, 6]
+ assert list(align.y2x.data) == [1, 1, 1, 2, 3, 4, 5, 6]
# multiple leading whitespace tokens
other_tokens = [" ", " ", "i listened to", "obama", "'", "s", "podcasts", "."]
spacy_tokens = ["i", "listened", "to", "obama", "'s", "podcasts."]
align = Alignment.from_strings(other_tokens, spacy_tokens)
assert list(align.x2y.lengths) == [0, 0, 3, 1, 1, 1, 1, 1]
- assert list(align.x2y.dataXd) == [0, 1, 2, 3, 4, 4, 5, 5]
+ assert list(align.x2y.data) == [0, 1, 2, 3, 4, 4, 5, 5]
assert list(align.y2x.lengths) == [1, 1, 1, 1, 2, 2]
- assert list(align.y2x.dataXd) == [2, 2, 2, 3, 4, 5, 6, 7]
+ assert list(align.y2x.data) == [2, 2, 2, 3, 4, 5, 6, 7]
# both with leading whitespace, not identical
other_tokens = [" ", " ", "i listened to", "obama", "'", "s", "podcasts", "."]
spacy_tokens = [" ", "i", "listened", "to", "obama", "'s", "podcasts."]
align = Alignment.from_strings(other_tokens, spacy_tokens)
assert list(align.x2y.lengths) == [1, 0, 3, 1, 1, 1, 1, 1]
- assert list(align.x2y.dataXd) == [0, 1, 2, 3, 4, 5, 5, 6, 6]
+ assert list(align.x2y.data) == [0, 1, 2, 3, 4, 5, 5, 6, 6]
assert list(align.y2x.lengths) == [1, 1, 1, 1, 1, 2, 2]
- assert list(align.y2x.dataXd) == [0, 2, 2, 2, 3, 4, 5, 6, 7]
+ assert list(align.y2x.data) == [0, 2, 2, 2, 3, 4, 5, 6, 7]
# same leading whitespace, different tokenization
other_tokens = [" ", " ", "i listened to", "obama", "'", "s", "podcasts", "."]
spacy_tokens = [" ", "i", "listened", "to", "obama", "'s", "podcasts."]
align = Alignment.from_strings(other_tokens, spacy_tokens)
assert list(align.x2y.lengths) == [1, 1, 3, 1, 1, 1, 1, 1]
- assert list(align.x2y.dataXd) == [0, 0, 1, 2, 3, 4, 5, 5, 6, 6]
+ assert list(align.x2y.data) == [0, 0, 1, 2, 3, 4, 5, 5, 6, 6]
assert list(align.y2x.lengths) == [2, 1, 1, 1, 1, 2, 2]
- assert list(align.y2x.dataXd) == [0, 1, 2, 2, 2, 3, 4, 5, 6, 7]
+ assert list(align.y2x.data) == [0, 1, 2, 2, 2, 3, 4, 5, 6, 7]
# only one with trailing whitespace
other_tokens = ["i listened to", "obama", "'", "s", "podcasts", ".", " "]
spacy_tokens = ["i", "listened", "to", "obama", "'s", "podcasts."]
align = Alignment.from_strings(other_tokens, spacy_tokens)
assert list(align.x2y.lengths) == [3, 1, 1, 1, 1, 1, 0]
- assert list(align.x2y.dataXd) == [0, 1, 2, 3, 4, 4, 5, 5]
+ assert list(align.x2y.data) == [0, 1, 2, 3, 4, 4, 5, 5]
assert list(align.y2x.lengths) == [1, 1, 1, 1, 2, 2]
- assert list(align.y2x.dataXd) == [0, 0, 0, 1, 2, 3, 4, 5]
+ assert list(align.y2x.data) == [0, 0, 0, 1, 2, 3, 4, 5]
# different trailing whitespace
other_tokens = ["i listened to", "obama", "'", "s", "podcasts", ".", " ", " "]
spacy_tokens = ["i", "listened", "to", "obama", "'s", "podcasts.", " "]
align = Alignment.from_strings(other_tokens, spacy_tokens)
assert list(align.x2y.lengths) == [3, 1, 1, 1, 1, 1, 1, 0]
- assert list(align.x2y.dataXd) == [0, 1, 2, 3, 4, 4, 5, 5, 6]
+ assert list(align.x2y.data) == [0, 1, 2, 3, 4, 4, 5, 5, 6]
assert list(align.y2x.lengths) == [1, 1, 1, 1, 2, 2, 1]
- assert list(align.y2x.dataXd) == [0, 0, 0, 1, 2, 3, 4, 5, 6]
+ assert list(align.y2x.data) == [0, 0, 0, 1, 2, 3, 4, 5, 6]
# same trailing whitespace, different tokenization
other_tokens = ["i listened to", "obama", "'", "s", "podcasts", ".", " ", " "]
spacy_tokens = ["i", "listened", "to", "obama", "'s", "podcasts.", " "]
align = Alignment.from_strings(other_tokens, spacy_tokens)
assert list(align.x2y.lengths) == [3, 1, 1, 1, 1, 1, 1, 1]
- assert list(align.x2y.dataXd) == [0, 1, 2, 3, 4, 4, 5, 5, 6, 6]
+ assert list(align.x2y.data) == [0, 1, 2, 3, 4, 4, 5, 5, 6, 6]
assert list(align.y2x.lengths) == [1, 1, 1, 1, 2, 2, 2]
- assert list(align.y2x.dataXd) == [0, 0, 0, 1, 2, 3, 4, 5, 6, 7]
+ assert list(align.y2x.data) == [0, 0, 0, 1, 2, 3, 4, 5, 6, 7]
# differing whitespace is allowed
other_tokens = ["a", " \n ", "b", "c"]
spacy_tokens = ["a", "b", " ", "c"]
align = Alignment.from_strings(other_tokens, spacy_tokens)
- assert list(align.x2y.dataXd) == [0, 1, 3]
- assert list(align.y2x.dataXd) == [0, 2, 3]
+ assert list(align.x2y.data) == [0, 1, 3]
+ assert list(align.y2x.data) == [0, 2, 3]
# other differences in whitespace are allowed
other_tokens = [" ", "a"]
@@ -1054,3 +1114,39 @@ def test_retokenized_docs(doc):
retokenizer.merge(doc1[0:2])
retokenizer.merge(doc1[5:7])
assert example.get_aligned("ORTH", as_string=True) == expected2
+
+
+def test_training_before_update(doc):
+ def before_update(nlp, args):
+ assert args["step"] == 0
+ assert args["epoch"] == 1
+
+ # Raise an error here as the rest of the loop
+ # will not run to completion due to uninitialized
+ # models.
+ raise ValueError("ran_before_update")
+
+ def generate_batch():
+ yield 1, [Example(doc, doc)]
+
+ nlp = spacy.blank("en")
+ nlp.add_pipe("tagger")
+ optimizer = Adam()
+ generator = train_while_improving(
+ nlp,
+ optimizer,
+ generate_batch(),
+ lambda: None,
+ dropout=0.1,
+ eval_frequency=100,
+ accumulate_gradient=10,
+ patience=10,
+ max_steps=100,
+ exclude=[],
+ annotating_components=[],
+ before_update=before_update,
+ )
+
+ with pytest.raises(ValueError, match="ran_before_update"):
+ for _ in generator:
+ pass
diff --git a/spacy/tests/util.py b/spacy/tests/util.py
index 365ea4349..d5f3c39ff 100644
--- a/spacy/tests/util.py
+++ b/spacy/tests/util.py
@@ -5,6 +5,7 @@ import srsly
from spacy.tokens import Doc
from spacy.vocab import Vocab
from spacy.util import make_tempdir # noqa: F401
+from spacy.training import split_bilu_label
from thinc.api import get_current_ops
@@ -40,7 +41,7 @@ def apply_transition_sequence(parser, doc, sequence):
desired state."""
for action_name in sequence:
if "-" in action_name:
- move, label = action_name.split("-")
+ move, label = split_bilu_label(action_name)
parser.add_label(label)
with parser.step_through(doc) as stepwise:
for transition in sequence:
diff --git a/spacy/tests/vocab_vectors/test_similarity.py b/spacy/tests/vocab_vectors/test_similarity.py
index 47cd1f060..1efcdd81e 100644
--- a/spacy/tests/vocab_vectors/test_similarity.py
+++ b/spacy/tests/vocab_vectors/test_similarity.py
@@ -1,6 +1,7 @@
import pytest
import numpy
from spacy.tokens import Doc
+from spacy.vocab import Vocab
from ..util import get_cosine, add_vecs_to_vocab
@@ -71,19 +72,17 @@ def test_vectors_similarity_DD(vocab, vectors):
def test_vectors_similarity_TD(vocab, vectors):
[(word1, vec1), (word2, vec2)] = vectors
doc = Doc(vocab, words=[word1, word2])
- with pytest.warns(UserWarning):
- assert isinstance(doc.similarity(doc[0]), float)
- assert isinstance(doc[0].similarity(doc), float)
- assert doc.similarity(doc[0]) == doc[0].similarity(doc)
+ assert isinstance(doc.similarity(doc[0]), float)
+ assert isinstance(doc[0].similarity(doc), float)
+ assert doc.similarity(doc[0]) == doc[0].similarity(doc)
def test_vectors_similarity_TS(vocab, vectors):
[(word1, vec1), (word2, vec2)] = vectors
doc = Doc(vocab, words=[word1, word2])
- with pytest.warns(UserWarning):
- assert isinstance(doc[:2].similarity(doc[0]), float)
- assert isinstance(doc[0].similarity(doc[-2]), float)
- assert doc[:2].similarity(doc[0]) == doc[0].similarity(doc[:2])
+ assert isinstance(doc[:2].similarity(doc[0]), float)
+ assert isinstance(doc[0].similarity(doc[:2]), float)
+ assert doc[:2].similarity(doc[0]) == doc[0].similarity(doc[:2])
def test_vectors_similarity_DS(vocab, vectors):
@@ -91,3 +90,21 @@ def test_vectors_similarity_DS(vocab, vectors):
doc = Doc(vocab, words=[word1, word2])
assert isinstance(doc.similarity(doc[:2]), float)
assert doc.similarity(doc[:2]) == doc[:2].similarity(doc)
+
+
+def test_vectors_similarity_no_vectors():
+ vocab = Vocab()
+ doc1 = Doc(vocab, words=["a", "b"])
+ doc2 = Doc(vocab, words=["c", "d", "e"])
+ with pytest.warns(UserWarning):
+ doc1.similarity(doc2)
+ with pytest.warns(UserWarning):
+ doc1.similarity(doc2[1])
+ with pytest.warns(UserWarning):
+ doc1.similarity(doc2[:2])
+ with pytest.warns(UserWarning):
+ doc2.similarity(doc1)
+ with pytest.warns(UserWarning):
+ doc2[1].similarity(doc1)
+ with pytest.warns(UserWarning):
+ doc2[:2].similarity(doc1)
diff --git a/spacy/tests/vocab_vectors/test_vectors.py b/spacy/tests/vocab_vectors/test_vectors.py
index ffd7489b2..70835816d 100644
--- a/spacy/tests/vocab_vectors/test_vectors.py
+++ b/spacy/tests/vocab_vectors/test_vectors.py
@@ -318,17 +318,15 @@ def test_vectors_lexeme_doc_similarity(vocab, text):
@pytest.mark.parametrize("text", [["apple", "orange", "juice"]])
def test_vectors_span_span_similarity(vocab, text):
doc = Doc(vocab, words=text)
- with pytest.warns(UserWarning):
- assert doc[0:2].similarity(doc[1:3]) == doc[1:3].similarity(doc[0:2])
- assert -1.0 < doc[0:2].similarity(doc[1:3]) < 1.0
+ assert doc[0:2].similarity(doc[1:3]) == doc[1:3].similarity(doc[0:2])
+ assert -1.0 < doc[0:2].similarity(doc[1:3]) < 1.0
@pytest.mark.parametrize("text", [["apple", "orange", "juice"]])
def test_vectors_span_doc_similarity(vocab, text):
doc = Doc(vocab, words=text)
- with pytest.warns(UserWarning):
- assert doc[0:2].similarity(doc) == doc.similarity(doc[0:2])
- assert -1.0 < doc[0:2].similarity(doc) < 1.0
+ assert doc[0:2].similarity(doc) == doc.similarity(doc[0:2])
+ assert -1.0 < doc[0:2].similarity(doc) < 1.0
@pytest.mark.parametrize(
@@ -455,6 +453,39 @@ def test_vectors_get_batch():
assert_equal(OPS.to_numpy(vecs), OPS.to_numpy(v.get_batch(words)))
+def test_vectors_deduplicate():
+ data = OPS.asarray([[1, 1], [2, 2], [3, 4], [1, 1], [3, 4]], dtype="f")
+ v = Vectors(data=data, keys=["a1", "b1", "c1", "a2", "c2"])
+ vocab = Vocab()
+ vocab.vectors = v
+ # duplicate vectors do not use the same keys
+ assert (
+ vocab.vectors.key2row[v.strings["a1"]] != vocab.vectors.key2row[v.strings["a2"]]
+ )
+ assert (
+ vocab.vectors.key2row[v.strings["c1"]] != vocab.vectors.key2row[v.strings["c2"]]
+ )
+ vocab.deduplicate_vectors()
+ # there are three unique vectors
+ assert vocab.vectors.shape[0] == 3
+ # the uniqued data is the same as the deduplicated data
+ assert_equal(
+ numpy.unique(OPS.to_numpy(vocab.vectors.data), axis=0),
+ OPS.to_numpy(vocab.vectors.data),
+ )
+ # duplicate vectors use the same keys now
+ assert (
+ vocab.vectors.key2row[v.strings["a1"]] == vocab.vectors.key2row[v.strings["a2"]]
+ )
+ assert (
+ vocab.vectors.key2row[v.strings["c1"]] == vocab.vectors.key2row[v.strings["c2"]]
+ )
+ # deduplicating again makes no changes
+ vocab_b = vocab.to_bytes()
+ vocab.deduplicate_vectors()
+ assert vocab_b == vocab.to_bytes()
+
+
@pytest.fixture()
def floret_vectors_hashvec_str():
"""The full hashvec table from floret with the settings:
@@ -595,3 +626,23 @@ def test_floret_vectors(floret_vectors_vec_str, floret_vectors_hashvec_str):
OPS.to_numpy(vocab_r[word].vector),
decimal=6,
)
+
+
+def test_equality():
+ vectors1 = Vectors(shape=(10, 10))
+ vectors2 = Vectors(shape=(10, 8))
+
+ assert vectors1 != vectors2
+
+ vectors2 = Vectors(shape=(10, 10))
+ assert vectors1 == vectors2
+
+ vectors1.add("hello", row=2)
+ assert vectors1 != vectors2
+
+ vectors2.add("hello", row=2)
+ assert vectors1 == vectors2
+
+ vectors1.resize((5, 9))
+ vectors2.resize((5, 9))
+ assert vectors1 == vectors2
diff --git a/spacy/tests/vocab_vectors/test_vocab_api.py b/spacy/tests/vocab_vectors/test_vocab_api.py
index 16cf80a08..b9c386eb8 100644
--- a/spacy/tests/vocab_vectors/test_vocab_api.py
+++ b/spacy/tests/vocab_vectors/test_vocab_api.py
@@ -1,8 +1,13 @@
+import os
+
import pytest
from spacy.attrs import IS_ALPHA, LEMMA, ORTH
+from spacy.lang.en import English
from spacy.parts_of_speech import NOUN, VERB
from spacy.vocab import Vocab
+from ..util import make_tempdir
+
@pytest.mark.issue(1868)
def test_issue1868():
@@ -59,3 +64,19 @@ def test_vocab_api_contains(en_vocab, text):
def test_vocab_writing_system(en_vocab):
assert en_vocab.writing_system["direction"] == "ltr"
assert en_vocab.writing_system["has_case"] is True
+
+
+def test_to_disk():
+ nlp = English()
+ with make_tempdir() as d:
+ nlp.vocab.to_disk(d)
+ assert "vectors" in os.listdir(d)
+ assert "lookups.bin" in os.listdir(d)
+
+
+def test_to_disk_exclude():
+ nlp = English()
+ with make_tempdir() as d:
+ nlp.vocab.to_disk(d, exclude=("vectors", "lookups"))
+ assert "vectors" not in os.listdir(d)
+ assert "lookups.bin" not in os.listdir(d)
diff --git a/spacy/tokenizer.pxd b/spacy/tokenizer.pxd
index fa38a1015..e6a072053 100644
--- a/spacy/tokenizer.pxd
+++ b/spacy/tokenizer.pxd
@@ -23,9 +23,10 @@ cdef class Tokenizer:
cdef object _infix_finditer
cdef object _rules
cdef PhraseMatcher _special_matcher
- # TODO next two are unused and should be removed in v4
+ # TODO convert to bool in v4
+ cdef int _faster_heuristics
+ # TODO next one is unused and should be removed in v4
# https://github.com/explosion/spaCy/pull/9150
- cdef int _unused_int1
cdef int _unused_int2
cdef Doc _tokenize_affixes(self, str string, bint with_special_cases)
diff --git a/spacy/tokenizer.pyx b/spacy/tokenizer.pyx
index 91f228032..0e75b5f7a 100644
--- a/spacy/tokenizer.pyx
+++ b/spacy/tokenizer.pyx
@@ -34,7 +34,7 @@ cdef class Tokenizer:
"""
def __init__(self, Vocab vocab, rules=None, prefix_search=None,
suffix_search=None, infix_finditer=None, token_match=None,
- url_match=None):
+ url_match=None, faster_heuristics=True):
"""Create a `Tokenizer`, to create `Doc` objects given unicode text.
vocab (Vocab): A storage container for lexical types.
@@ -43,7 +43,7 @@ cdef class Tokenizer:
`re.compile(string).search` to match prefixes.
suffix_search (callable): A function matching the signature of
`re.compile(string).search` to match suffixes.
- `infix_finditer` (callable): A function matching the signature of
+ infix_finditer (callable): A function matching the signature of
`re.compile(string).finditer` to find infixes.
token_match (callable): A function matching the signature of
`re.compile(string).match`, for matching strings to be
@@ -51,6 +51,9 @@ cdef class Tokenizer:
url_match (callable): A function matching the signature of
`re.compile(string).match`, for matching strings to be
recognized as urls.
+ faster_heuristics (bool): Whether to restrict the final
+ Matcher-based pass for rules to those containing affixes or space.
+ Defaults to True.
EXAMPLE:
>>> tokenizer = Tokenizer(nlp.vocab)
@@ -66,6 +69,7 @@ cdef class Tokenizer:
self.suffix_search = suffix_search
self.infix_finditer = infix_finditer
self.vocab = vocab
+ self.faster_heuristics = faster_heuristics
self._rules = {}
self._special_matcher = PhraseMatcher(self.vocab)
self._load_special_cases(rules)
@@ -122,6 +126,14 @@ cdef class Tokenizer:
self._specials = PreshMap()
self._load_special_cases(rules)
+ property faster_heuristics:
+ def __get__(self):
+ return bool(self._faster_heuristics)
+
+ def __set__(self, faster_heuristics):
+ self._faster_heuristics = bool(faster_heuristics)
+ self._reload_special_cases()
+
def __reduce__(self):
args = (self.vocab,
self.rules,
@@ -287,7 +299,7 @@ cdef class Tokenizer:
spans = [doc[match.start:match.end] for match in filtered]
cdef bint modify_in_place = True
cdef int curr_length = doc.length
- cdef int max_length
+ cdef int max_length = 0
cdef int span_length_diff = 0
span_data = {}
for span in spans:
@@ -602,7 +614,7 @@ cdef class Tokenizer:
self.mem.free(stale_special)
self._rules[string] = substrings
self._flush_cache()
- if self.find_prefix(string) or self.find_infix(string) or self.find_suffix(string) or " " in string:
+ if not self.faster_heuristics or self.find_prefix(string) or self.find_infix(string) or self.find_suffix(string) or " " in string:
self._special_matcher.add(string, None, self._tokenize_affixes(string, False))
def _reload_special_cases(self):
@@ -643,6 +655,10 @@ cdef class Tokenizer:
for substring in text.split():
suffixes = []
while substring:
+ if substring in special_cases:
+ tokens.extend(("SPECIAL-" + str(i + 1), self.vocab.strings[e[ORTH]]) for i, e in enumerate(special_cases[substring]))
+ substring = ''
+ continue
while prefix_search(substring) or suffix_search(substring):
if token_match(substring):
tokens.append(("TOKEN_MATCH", substring))
@@ -773,7 +789,8 @@ cdef class Tokenizer:
"infix_finditer": lambda: _get_regex_pattern(self.infix_finditer),
"token_match": lambda: _get_regex_pattern(self.token_match),
"url_match": lambda: _get_regex_pattern(self.url_match),
- "exceptions": lambda: dict(sorted(self._rules.items()))
+ "exceptions": lambda: dict(sorted(self._rules.items())),
+ "faster_heuristics": lambda: self.faster_heuristics,
}
return util.to_bytes(serializers, exclude)
@@ -794,7 +811,8 @@ cdef class Tokenizer:
"infix_finditer": lambda b: data.setdefault("infix_finditer", b),
"token_match": lambda b: data.setdefault("token_match", b),
"url_match": lambda b: data.setdefault("url_match", b),
- "exceptions": lambda b: data.setdefault("rules", b)
+ "exceptions": lambda b: data.setdefault("rules", b),
+ "faster_heuristics": lambda b: data.setdefault("faster_heuristics", b),
}
# reset all properties and flush all caches (through rules),
# reset rules first so that _reload_special_cases is trivial/fast as
@@ -818,6 +836,8 @@ cdef class Tokenizer:
self.url_match = re.compile(data["url_match"]).match
if "rules" in data and isinstance(data["rules"], dict):
self.rules = data["rules"]
+ if "faster_heuristics" in data:
+ self.faster_heuristics = data["faster_heuristics"]
return self
diff --git a/spacy/tokens/_dict_proxies.py b/spacy/tokens/_dict_proxies.py
index 8643243fa..6edcce13d 100644
--- a/spacy/tokens/_dict_proxies.py
+++ b/spacy/tokens/_dict_proxies.py
@@ -1,10 +1,11 @@
-from typing import Iterable, Tuple, Union, Optional, TYPE_CHECKING
+from typing import Dict, Iterable, List, Tuple, Union, Optional, TYPE_CHECKING
+import warnings
import weakref
from collections import UserDict
import srsly
from .span_group import SpanGroup
-from ..errors import Errors
+from ..errors import Errors, Warnings
if TYPE_CHECKING:
@@ -16,7 +17,7 @@ if TYPE_CHECKING:
# Why inherit from UserDict instead of dict here?
# Well, the 'dict' class doesn't necessarily delegate everything nicely,
# for performance reasons. The UserDict is slower but better behaved.
-# See https://treyhunner.com/2019/04/why-you-shouldnt-inherit-from-list-and-dict-in-python/0ww
+# See https://treyhunner.com/2019/04/why-you-shouldnt-inherit-from-list-and-dict-in-python/
class SpanGroups(UserDict):
"""A dict-like proxy held by the Doc, to control access to span groups."""
@@ -41,23 +42,65 @@ class SpanGroups(UserDict):
def copy(self, doc: Optional["Doc"] = None) -> "SpanGroups":
if doc is None:
doc = self._ensure_doc()
- return SpanGroups(doc).from_bytes(self.to_bytes())
+ data_copy = ((k, v.copy(doc=doc)) for k, v in self.items())
+ return SpanGroups(doc, items=data_copy)
+
+ def setdefault(self, key, default=None):
+ if not isinstance(default, SpanGroup):
+ if default is None:
+ spans = []
+ else:
+ spans = default
+ default = self._make_span_group(key, spans)
+ return super().setdefault(key, default=default)
def to_bytes(self) -> bytes:
- # We don't need to serialize this as a dict, because the groups
- # know their names.
+ # We serialize this as a dict in order to track the key(s) a SpanGroup
+ # is a value of (in a backward- and forward-compatible way), since
+ # a SpanGroup can have a key that doesn't match its `.name` (See #10685)
if len(self) == 0:
return self._EMPTY_BYTES
- msg = [value.to_bytes() for value in self.values()]
+ msg: Dict[bytes, List[str]] = {}
+ for key, value in self.items():
+ msg.setdefault(value.to_bytes(), []).append(key)
return srsly.msgpack_dumps(msg)
def from_bytes(self, bytes_data: bytes) -> "SpanGroups":
- msg = [] if bytes_data == self._EMPTY_BYTES else srsly.msgpack_loads(bytes_data)
+ # backwards-compatibility: bytes_data may be one of:
+ # b'', a serialized empty list, a serialized list of SpanGroup bytes
+ # or a serialized dict of SpanGroup bytes -> keys
+ msg = (
+ []
+ if not bytes_data or bytes_data == self._EMPTY_BYTES
+ else srsly.msgpack_loads(bytes_data)
+ )
self.clear()
doc = self._ensure_doc()
- for value_bytes in msg:
- group = SpanGroup(doc).from_bytes(value_bytes)
- self[group.name] = group
+ if isinstance(msg, list):
+ # This is either the 1st version of `SpanGroups` serialization
+ # or there were no SpanGroups serialized
+ for value_bytes in msg:
+ group = SpanGroup(doc).from_bytes(value_bytes)
+ if group.name in self:
+ # Display a warning if `msg` contains `SpanGroup`s
+ # that have the same .name (attribute).
+ # Because, for `SpanGroups` serialized as lists,
+ # only 1 SpanGroup per .name is loaded. (See #10685)
+ warnings.warn(
+ Warnings.W120.format(
+ group_name=group.name, group_values=self[group.name]
+ )
+ )
+ self[group.name] = group
+ else:
+ for value_bytes, keys in msg.items():
+ group = SpanGroup(doc).from_bytes(value_bytes)
+ # Deserialize `SpanGroup`s as copies because it's possible for two
+ # different `SpanGroup`s (pre-serialization) to have the same bytes
+ # (since they can have the same `.name`).
+ self[keys[0]] = group
+ for key in keys[1:]:
+ self[key] = group.copy()
return self
def _ensure_doc(self) -> "Doc":
diff --git a/spacy/tokens/_serialize.py b/spacy/tokens/_serialize.py
index 2b72adb4d..c4e8f26f4 100644
--- a/spacy/tokens/_serialize.py
+++ b/spacy/tokens/_serialize.py
@@ -147,7 +147,8 @@ class DocBin:
doc = Doc(vocab, words=tokens[:, orth_col], spaces=spaces) # type: ignore
doc = doc.from_array(self.attrs, tokens) # type: ignore
doc.cats = self.cats[i]
- if self.span_groups[i] != SpanGroups._EMPTY_BYTES:
+ # backwards-compatibility: may be b'' or serialized empty list
+ if self.span_groups[i] and self.span_groups[i] != SpanGroups._EMPTY_BYTES:
doc.spans.from_bytes(self.span_groups[i])
else:
doc.spans.clear()
diff --git a/spacy/tokens/doc.pyi b/spacy/tokens/doc.pyi
index 7e9340d58..f0cdaee87 100644
--- a/spacy/tokens/doc.pyi
+++ b/spacy/tokens/doc.pyi
@@ -72,7 +72,7 @@ class Doc:
lemmas: Optional[List[str]] = ...,
heads: Optional[List[int]] = ...,
deps: Optional[List[str]] = ...,
- sent_starts: Optional[List[Union[bool, None]]] = ...,
+ sent_starts: Optional[List[Union[bool, int, None]]] = ...,
ents: Optional[List[str]] = ...,
) -> None: ...
@property
@@ -170,6 +170,9 @@ class Doc:
def extend_tensor(self, tensor: Floats2d) -> None: ...
def retokenize(self) -> Retokenizer: ...
def to_json(self, underscore: Optional[List[str]] = ...) -> Dict[str, Any]: ...
+ def from_json(
+ self, doc_json: Dict[str, Any] = ..., validate: bool = False
+ ) -> Doc: ...
def to_utf8_array(self, nr_char: int = ...) -> Ints2d: ...
@staticmethod
def _get_array_attrs() -> Tuple[Any]: ...
diff --git a/spacy/tokens/doc.pyx b/spacy/tokens/doc.pyx
index d33764ac9..075bc4d15 100644
--- a/spacy/tokens/doc.pyx
+++ b/spacy/tokens/doc.pyx
@@ -1,4 +1,6 @@
# cython: infer_types=True, bounds_check=False, profile=True
+from typing import Set
+
cimport cython
cimport numpy as np
from libc.string cimport memcpy
@@ -11,7 +13,7 @@ from enum import Enum
import itertools
import numpy
import srsly
-from thinc.api import get_array_module
+from thinc.api import get_array_module, get_current_ops
from thinc.util import copy_array
import warnings
@@ -31,10 +33,11 @@ from ..errors import Errors, Warnings
from ..morphology import Morphology
from .. import util
from .. import parts_of_speech
+from .. import schemas
from .underscore import Underscore, get_ext_args
from ._retokenize import Retokenizer
from ._serialize import ALL_ATTRS as DOCBIN_ALL_ATTRS
-
+from ..util import get_words_and_spaces
DEF PADDING = 5
@@ -214,9 +217,9 @@ cdef class Doc:
head in the doc. Defaults to None.
deps (Optional[List[str]]): A list of unicode strings, of the same
length as words, to assign as token.dep. Defaults to None.
- sent_starts (Optional[List[Union[bool, None]]]): A list of values, of
- the same length as words, to assign as token.is_sent_start. Will be
- overridden by heads if heads is provided. Defaults to None.
+ sent_starts (Optional[List[Union[bool, int, None]]]): A list of values,
+ of the same length as words, to assign as token.is_sent_start. Will
+ be overridden by heads if heads is provided. Defaults to None.
ents (Optional[List[str]]): A list of unicode strings, of the same
length as words, as IOB tags to assign as token.ent_iob and
token.ent_type. Defaults to None.
@@ -282,6 +285,7 @@ cdef class Doc:
heads = [0] * len(deps)
if heads and not deps:
raise ValueError(Errors.E1017)
+ sent_starts = list(sent_starts) if sent_starts is not None else None
if sent_starts is not None:
for i in range(len(sent_starts)):
if sent_starts[i] is True:
@@ -297,12 +301,11 @@ cdef class Doc:
ent_iobs = None
ent_types = None
if ents is not None:
+ ents = [ent if ent != "" else None for ent in ents]
iob_strings = Token.iob_strings()
# make valid IOB2 out of IOB1 or IOB2
for i, ent in enumerate(ents):
- if ent is "":
- ents[i] = None
- elif ent is not None and not isinstance(ent, str):
+ if ent is not None and not isinstance(ent, str):
raise ValueError(Errors.E177.format(tag=ent))
if i < len(ents) - 1:
# OI -> OB
@@ -356,6 +359,7 @@ cdef class Doc:
for annot in annotations:
if annot:
if annot is heads or annot is sent_starts or annot is ent_iobs:
+ annot = numpy.array(annot, dtype=numpy.int32).astype(numpy.uint64)
for i in range(len(words)):
if attrs.ndim == 1:
attrs[i] = annot[i]
@@ -414,6 +418,7 @@ cdef class Doc:
"""
# empty docs are always annotated
+ input_attr = attr
if self.length == 0:
return True
cdef int i
@@ -423,6 +428,10 @@ cdef class Doc:
elif attr == "IS_SENT_END" or attr == self.vocab.strings["IS_SENT_END"]:
attr = SENT_START
attr = intify_attr(attr)
+ if attr is None:
+ raise ValueError(
+ Errors.E1037.format(attr=input_attr)
+ )
# adjust attributes
if attr == HEAD:
# HEAD does not have an unset state, so rely on DEP
@@ -511,7 +520,7 @@ cdef class Doc:
def doc(self):
return self
- def char_span(self, int start_idx, int end_idx, label=0, kb_id=0, vector=None, alignment_mode="strict"):
+ def char_span(self, int start_idx, int end_idx, label=0, kb_id=0, vector=None, alignment_mode="strict", span_id=0):
"""Create a `Span` object from the slice
`doc.text[start_idx : end_idx]`. Returns None if no valid `Span` can be
created.
@@ -570,7 +579,7 @@ cdef class Doc:
start += 1
# Currently we have the token index, we want the range-end index
end += 1
- cdef Span span = Span(self, start, end, label=label, kb_id=kb_id, vector=vector)
+ cdef Span span = Span(self, start, end, label=label, kb_id=kb_id, span_id=span_id, vector=vector)
return span
def similarity(self, other):
@@ -599,7 +608,8 @@ cdef class Doc:
if self.vocab.vectors.n_keys == 0:
warnings.warn(Warnings.W007.format(obj="Doc"))
if self.vector_norm == 0 or other.vector_norm == 0:
- warnings.warn(Warnings.W008.format(obj="Doc"))
+ if not self.has_vector or not other.has_vector:
+ warnings.warn(Warnings.W008.format(obj="Doc"))
return 0.0
vector = self.vector
xp = get_array_module(vector)
@@ -619,7 +629,7 @@ cdef class Doc:
if "has_vector" in self.user_hooks:
return self.user_hooks["has_vector"](self)
elif self.vocab.vectors.size:
- return True
+ return any(token.has_vector for token in self)
elif self.tensor.size:
return True
else:
@@ -708,6 +718,7 @@ cdef class Doc:
cdef int start = -1
cdef attr_t label = 0
cdef attr_t kb_id = 0
+ cdef attr_t ent_id = 0
output = []
for i in range(self.length):
token = &self.c[i]
@@ -718,18 +729,20 @@ cdef class Doc:
elif token.ent_iob == 2 or token.ent_iob == 0 or \
(token.ent_iob == 3 and token.ent_type == 0):
if start != -1:
- output.append(Span(self, start, i, label=label, kb_id=kb_id))
+ output.append(Span(self, start, i, label=label, kb_id=kb_id, span_id=ent_id))
start = -1
label = 0
kb_id = 0
+ ent_id = 0
elif token.ent_iob == 3:
if start != -1:
- output.append(Span(self, start, i, label=label, kb_id=kb_id))
+ output.append(Span(self, start, i, label=label, kb_id=kb_id, span_id=ent_id))
start = i
label = token.ent_type
kb_id = token.ent_kb_id
+ ent_id = token.ent_id
if start != -1:
- output.append(Span(self, start, self.length, label=label, kb_id=kb_id))
+ output.append(Span(self, start, self.length, label=label, kb_id=kb_id, span_id=ent_id))
# remove empty-label spans
output = [o for o in output if o.label_ != ""]
return tuple(output)
@@ -738,14 +751,14 @@ cdef class Doc:
# TODO:
# 1. Test basic data-driven ORTH gazetteer
# 2. Test more nuanced date and currency regex
- cdef attr_t entity_type, kb_id
+ cdef attr_t entity_type, kb_id, ent_id
cdef int ent_start, ent_end
ent_spans = []
for ent_info in ents:
- entity_type_, kb_id, ent_start, ent_end = get_entity_info(ent_info)
+ entity_type_, kb_id, ent_start, ent_end, ent_id = get_entity_info(ent_info)
if isinstance(entity_type_, str):
self.vocab.strings.add(entity_type_)
- span = Span(self, ent_start, ent_end, label=entity_type_, kb_id=kb_id)
+ span = Span(self, ent_start, ent_end, label=entity_type_, kb_id=kb_id, span_id=ent_id)
ent_spans.append(span)
self.set_ents(ent_spans, default=SetEntsDefault.outside)
@@ -796,6 +809,9 @@ cdef class Doc:
self.c[i].ent_iob = 1
self.c[i].ent_type = span.label
self.c[i].ent_kb_id = span.kb_id
+ # for backwards compatibility in v3, only set ent_id from
+ # span.id if it's set, otherwise don't override
+ self.c[i].ent_id = span.id if span.id else self.c[i].ent_id
for span in blocked:
for i in range(span.start, span.end):
self.c[i].ent_iob = 3
@@ -1108,14 +1124,19 @@ cdef class Doc:
return self
@staticmethod
- def from_docs(docs, ensure_whitespace=True, attrs=None):
+ def from_docs(docs, ensure_whitespace=True, attrs=None, *, exclude=tuple()):
"""Concatenate multiple Doc objects to form a new one. Raises an error
if the `Doc` objects do not all share the same `Vocab`.
docs (list): A list of Doc objects.
- ensure_whitespace (bool): Insert a space between two adjacent docs whenever the first doc does not end in whitespace.
- attrs (list): Optional list of attribute ID ints or attribute name strings.
- RETURNS (Doc): A doc that contains the concatenated docs, or None if no docs were given.
+ ensure_whitespace (bool): Insert a space between two adjacent docs
+ whenever the first doc does not end in whitespace.
+ attrs (list): Optional list of attribute ID ints or attribute name
+ strings.
+ exclude (Iterable[str]): Doc attributes to exclude. Supported
+ attributes: `spans`, `tensor`, `user_data`.
+ RETURNS (Doc): A doc that contains the concatenated docs, or None if no
+ docs were given.
DOCS: https://spacy.io/api/doc#from_docs
"""
@@ -1145,31 +1166,34 @@ cdef class Doc:
concat_words.extend(t.text for t in doc)
concat_spaces.extend(bool(t.whitespace_) for t in doc)
- for key, value in doc.user_data.items():
- if isinstance(key, tuple) and len(key) == 4 and key[0] == "._.":
- data_type, name, start, end = key
- if start is not None or end is not None:
- start += char_offset
- if end is not None:
- end += char_offset
- concat_user_data[(data_type, name, start, end)] = copy.copy(value)
+ if "user_data" not in exclude:
+ for key, value in doc.user_data.items():
+ if isinstance(key, tuple) and len(key) == 4 and key[0] == "._.":
+ data_type, name, start, end = key
+ if start is not None or end is not None:
+ start += char_offset
+ if end is not None:
+ end += char_offset
+ concat_user_data[(data_type, name, start, end)] = copy.copy(value)
+ else:
+ warnings.warn(Warnings.W101.format(name=name))
else:
- warnings.warn(Warnings.W101.format(name=name))
- else:
- warnings.warn(Warnings.W102.format(key=key, value=value))
- for key in doc.spans:
- # if a spans key is in any doc, include it in the merged doc
- # even if it is empty
- if key not in concat_spans:
- concat_spans[key] = []
- for span in doc.spans[key]:
- concat_spans[key].append((
- span.start_char + char_offset,
- span.end_char + char_offset,
- span.label,
- span.kb_id,
- span.text, # included as a check
- ))
+ warnings.warn(Warnings.W102.format(key=key, value=value))
+ if "spans" not in exclude:
+ for key in doc.spans:
+ # if a spans key is in any doc, include it in the merged doc
+ # even if it is empty
+ if key not in concat_spans:
+ concat_spans[key] = []
+ for span in doc.spans[key]:
+ concat_spans[key].append((
+ span.start_char + char_offset,
+ span.end_char + char_offset,
+ span.label,
+ span.kb_id,
+ span.id,
+ span.text, # included as a check
+ ))
char_offset += len(doc.text)
if len(doc) > 0 and ensure_whitespace and not doc[-1].is_space and not bool(doc[-1].whitespace_):
char_offset += 1
@@ -1203,13 +1227,18 @@ cdef class Doc:
span_tuple[1],
label=span_tuple[2],
kb_id=span_tuple[3],
+ span_id=span_tuple[4],
)
- text = span_tuple[4]
+ text = span_tuple[5]
if span is not None and span.text == text:
concat_doc.spans[key].append(span)
else:
raise ValueError(Errors.E873.format(key=key, text=text))
+ if "tensor" not in exclude and any(len(doc) for doc in docs):
+ ops = get_current_ops()
+ concat_doc.tensor = ops.xp.vstack([ops.asarray(doc.tensor) for doc in docs if len(doc)])
+
return concat_doc
def get_lca_matrix(self):
@@ -1451,22 +1480,166 @@ cdef class Doc:
remove_label_if_necessary(attributes[i])
retokenizer.merge(span, attributes[i])
+ def from_json(self, doc_json, *, validate=False):
+ """Convert a JSON document generated by Doc.to_json() to a Doc.
+
+ doc_json (Dict): JSON representation of doc object to load.
+ validate (bool): Whether to validate `doc_json` against the expected schema.
+ Defaults to False.
+ RETURNS (Doc): A doc instance corresponding to the specified JSON representation.
+ """
+
+ if validate:
+ schema_validation_message = schemas.validate(schemas.DocJSONSchema, doc_json)
+ if schema_validation_message:
+ raise ValueError(Errors.E1038.format(message=schema_validation_message))
+
+ ### Token-level properties ###
+
+ words = []
+ token_attrs_ids = (POS, HEAD, DEP, LEMMA, TAG, MORPH)
+ # Map annotation type IDs to their string equivalents.
+ token_attrs = {t: self.vocab.strings[t].lower() for t in token_attrs_ids}
+ token_annotations = {}
+
+ # Gather token-level properties.
+ for token_json in doc_json["tokens"]:
+ words.append(doc_json["text"][token_json["start"]:token_json["end"]])
+ for attr, attr_json in token_attrs.items():
+ if attr_json in token_json:
+ if token_json["id"] == 0 and attr not in token_annotations:
+ token_annotations[attr] = []
+ elif attr not in token_annotations:
+ raise ValueError(Errors.E1040.format(partial_attrs=attr))
+ token_annotations[attr].append(token_json[attr_json])
+
+ # Initialize doc instance.
+ start = 0
+ cdef const LexemeC* lex
+ cdef bint has_space
+ reconstructed_words, spaces = get_words_and_spaces(words, doc_json["text"])
+ assert words == reconstructed_words
+
+ for word, has_space in zip(words, spaces):
+ lex = self.vocab.get(self.mem, word)
+ self.push_back(lex, has_space)
+
+ # Set remaining token-level attributes via Doc.from_array().
+ if HEAD in token_annotations:
+ token_annotations[HEAD] = [
+ head - i for i, head in enumerate(token_annotations[HEAD])
+ ]
+
+ if DEP in token_annotations and HEAD not in token_annotations:
+ token_annotations[HEAD] = [0] * len(token_annotations[DEP])
+ if HEAD in token_annotations and DEP not in token_annotations:
+ raise ValueError(Errors.E1017)
+ if POS in token_annotations:
+ for pp in set(token_annotations[POS]):
+ if pp not in parts_of_speech.IDS:
+ raise ValueError(Errors.E1021.format(pp=pp))
+
+ # Collect token attributes, assert all tokens have exactly the same set of attributes.
+ attrs = []
+ partial_attrs: Set[str] = set()
+ for attr in token_attrs.keys():
+ if attr in token_annotations:
+ if len(token_annotations[attr]) != len(words):
+ partial_attrs.add(token_attrs[attr])
+ attrs.append(attr)
+ if len(partial_attrs):
+ raise ValueError(Errors.E1040.format(partial_attrs=partial_attrs))
+
+ # If there are any other annotations, set them.
+ if attrs:
+ array = self.to_array(attrs)
+ if array.ndim == 1:
+ array = numpy.reshape(array, (array.size, 1))
+ j = 0
+
+ for j, (attr, annot) in enumerate(token_annotations.items()):
+ if attr is HEAD:
+ annot = numpy.array(annot, dtype=numpy.int32).astype(numpy.uint64)
+ for i in range(len(words)):
+ array[i, j] = annot[i]
+ elif attr is MORPH:
+ for i in range(len(words)):
+ array[i, j] = self.vocab.morphology.add(annot[i])
+ else:
+ for i in range(len(words)):
+ array[i, j] = self.vocab.strings.add(annot[i])
+ self.from_array(attrs, array)
+
+ ### Span/document properties ###
+
+ # Complement other document-level properties (cats, spans, ents).
+ self.cats = doc_json.get("cats", {})
+
+ # Set sentence boundaries, if dependency parser not available but sentences are specified in JSON.
+ if not self.has_annotation("DEP"):
+ for sent in doc_json.get("sents", {}):
+ char_span = self.char_span(sent["start"], sent["end"])
+ if char_span is None:
+ raise ValueError(Errors.E1039.format(obj="sentence", start=sent["start"], end=sent["end"]))
+ char_span[0].is_sent_start = True
+ for token in char_span[1:]:
+ token.is_sent_start = False
+
+
+ for span_group in doc_json.get("spans", {}):
+ spans = []
+ for span in doc_json["spans"][span_group]:
+ char_span = self.char_span(span["start"], span["end"], span["label"], span["kb_id"])
+ if char_span is None:
+ raise ValueError(Errors.E1039.format(obj="span", start=span["start"], end=span["end"]))
+ spans.append(char_span)
+ self.spans[span_group] = spans
+
+ if "ents" in doc_json:
+ ents = []
+ for ent in doc_json["ents"]:
+ char_span = self.char_span(ent["start"], ent["end"], ent["label"])
+ if char_span is None:
+ raise ValueError(Errors.E1039.format(obj="entity"), start=ent["start"], end=ent["end"])
+ ents.append(char_span)
+ self.ents = ents
+
+ # Add custom attributes for the whole Doc object.
+ for attr in doc_json.get("_", {}):
+ if not Doc.has_extension(attr):
+ Doc.set_extension(attr)
+ self._.set(attr, doc_json["_"][attr])
+
+ for token_attr in doc_json.get("underscore_token", {}):
+ if not Token.has_extension(token_attr):
+ Token.set_extension(token_attr)
+ for token_data in doc_json["underscore_token"][token_attr]:
+ start = token_by_char(self.c, self.length, token_data["start"])
+ value = token_data["value"]
+ self[start]._.set(token_attr, value)
+
+ for span_attr in doc_json.get("underscore_span", {}):
+ if not Span.has_extension(span_attr):
+ Span.set_extension(span_attr)
+ for span_data in doc_json["underscore_span"][span_attr]:
+ value = span_data["value"]
+ self.char_span(span_data["start"], span_data["end"])._.set(span_attr, value)
+ return self
+
def to_json(self, underscore=None):
"""Convert a Doc to JSON.
underscore (list): Optional list of string names of custom doc._.
attributes. Attribute values need to be JSON-serializable. Values will
be added to an "_" key in the data, e.g. "_": {"foo": "bar"}.
- RETURNS (dict): The data in spaCy's JSON format.
+ RETURNS (dict): The data in JSON format.
"""
data = {"text": self.text}
if self.has_annotation("ENT_IOB"):
- data["ents"] = [{"start": ent.start_char, "end": ent.end_char,
- "label": ent.label_} for ent in self.ents]
+ data["ents"] = [{"start": ent.start_char, "end": ent.end_char, "label": ent.label_} for ent in self.ents]
if self.has_annotation("SENT_START"):
sents = list(self.sents)
- data["sents"] = [{"start": sent.start_char, "end": sent.end_char}
- for sent in sents]
+ data["sents"] = [{"start": sent.start_char, "end": sent.end_char} for sent in sents]
if self.cats:
data["cats"] = self.cats
data["tokens"] = []
@@ -1486,15 +1659,59 @@ cdef class Doc:
token_data["dep"] = token.dep_
token_data["head"] = token.head.i
data["tokens"].append(token_data)
+
+ if self.spans:
+ data["spans"] = {}
+ for span_group in self.spans:
+ data["spans"][span_group] = []
+ for span in self.spans[span_group]:
+ span_data = {"start": span.start_char, "end": span.end_char, "label": span.label_, "kb_id": span.kb_id_}
+ data["spans"][span_group].append(span_data)
+
if underscore:
- data["_"] = {}
+ user_keys = set()
+ # Handle doc attributes with .get to include values from getters
+ # and not only values stored in user_data, for backwards
+ # compatibility
for attr in underscore:
- if not self.has_extension(attr):
+ if self.has_extension(attr):
+ if "_" not in data:
+ data["_"] = {}
+ value = self._.get(attr)
+ if not srsly.is_json_serializable(value):
+ raise ValueError(Errors.E107.format(attr=attr, value=repr(value)))
+ data["_"][attr] = value
+ user_keys.add(attr)
+ # Token and span attributes only include values stored in user_data
+ # and not values generated by getters
+ if self.user_data:
+ for data_key, value in self.user_data.copy().items():
+ if type(data_key) == tuple and len(data_key) >= 4 and data_key[0] == "._.":
+ attr = data_key[1]
+ start = data_key[2]
+ end = data_key[3]
+ if attr in underscore:
+ user_keys.add(attr)
+ if not srsly.is_json_serializable(value):
+ raise ValueError(Errors.E107.format(attr=attr, value=repr(value)))
+ # Token attribute
+ if start is not None and end is None:
+ if "underscore_token" not in data:
+ data["underscore_token"] = {}
+ if attr not in data["underscore_token"]:
+ data["underscore_token"][attr] = []
+ data["underscore_token"][attr].append({"start": start, "value": value})
+ # Span attribute
+ elif start is not None and end is not None:
+ if "underscore_span" not in data:
+ data["underscore_span"] = {}
+ if attr not in data["underscore_span"]:
+ data["underscore_span"][attr] = []
+ data["underscore_span"][attr].append({"start": start, "end": end, "value": value})
+
+ for attr in underscore:
+ if attr not in user_keys:
raise ValueError(Errors.E106.format(attr=attr, opts=underscore))
- value = self._.get(attr)
- if not srsly.is_json_serializable(value):
- raise ValueError(Errors.E107.format(attr=attr, value=repr(value)))
- data["_"][attr] = value
return data
def to_utf8_array(self, int nr_char=-1):
@@ -1712,18 +1929,17 @@ cdef int [:,:] _get_lca_matrix(Doc doc, int start, int end):
def pickle_doc(doc):
bytes_data = doc.to_bytes(exclude=["vocab", "user_data", "user_hooks"])
hooks_and_data = (doc.user_data, doc.user_hooks, doc.user_span_hooks,
- doc.user_token_hooks, doc._context)
+ doc.user_token_hooks)
return (unpickle_doc, (doc.vocab, srsly.pickle_dumps(hooks_and_data), bytes_data))
def unpickle_doc(vocab, hooks_and_data, bytes_data):
- user_data, doc_hooks, span_hooks, token_hooks, _context = srsly.pickle_loads(hooks_and_data)
+ user_data, doc_hooks, span_hooks, token_hooks = srsly.pickle_loads(hooks_and_data)
doc = Doc(vocab, user_data=user_data).from_bytes(bytes_data, exclude=["user_data"])
doc.user_hooks.update(doc_hooks)
doc.user_span_hooks.update(span_hooks)
doc.user_token_hooks.update(token_hooks)
- doc._context = _context
return doc
@@ -1747,16 +1963,18 @@ def fix_attributes(doc, attributes):
def get_entity_info(ent_info):
+ ent_kb_id = 0
+ ent_id = 0
if isinstance(ent_info, Span):
ent_type = ent_info.label
ent_kb_id = ent_info.kb_id
start = ent_info.start
end = ent_info.end
+ ent_id = ent_info.id
elif len(ent_info) == 3:
ent_type, start, end = ent_info
- ent_kb_id = 0
elif len(ent_info) == 4:
ent_type, ent_kb_id, start, end = ent_info
else:
ent_id, ent_kb_id, ent_type, start, end = ent_info
- return ent_type, ent_kb_id, start, end
+ return ent_type, ent_kb_id, start, end, ent_id
diff --git a/spacy/tokens/graph.pyx b/spacy/tokens/graph.pyx
index 9351435f8..adc4d23c8 100644
--- a/spacy/tokens/graph.pyx
+++ b/spacy/tokens/graph.pyx
@@ -9,6 +9,8 @@ cimport cython
import weakref
from preshed.maps cimport map_get_unless_missing
from murmurhash.mrmr cimport hash64
+
+from .. import Errors
from ..typedefs cimport hash_t
from ..strings import get_string_id
from ..structs cimport EdgeC, GraphC
@@ -68,7 +70,7 @@ cdef class Node:
"""
cdef int length = graph.c.nodes.size()
if i >= length or -i >= length:
- raise IndexError(f"Node index {i} out of bounds ({length})")
+ raise IndexError(Errors.E1034.format(i=i, length=length))
if i < 0:
i += length
self.graph = graph
@@ -88,7 +90,7 @@ cdef class Node:
"""Get a token index from the node's set of tokens."""
length = self.graph.c.nodes[self.i].size()
if i >= length or -i >= length:
- raise IndexError(f"Token index {i} out of bounds ({length})")
+ raise IndexError(Errors.E1035.format(i=i, length=length))
if i < 0:
i += length
return self.graph.c.nodes[self.i][i]
@@ -306,7 +308,7 @@ cdef class NoneNode(Node):
self.i = -1
def __getitem__(self, int i):
- raise IndexError("Cannot index into NoneNode.")
+ raise IndexError(Errors.E1036)
def __len__(self):
return 0
@@ -484,7 +486,6 @@ cdef class Graph:
for idx in indices:
node.push_back(idx)
i = add_node(&self.c, node)
- print("Add node", indices, i)
return Node(self, i)
def get_node(self, indices) -> Node:
@@ -501,7 +502,6 @@ cdef class Graph:
if node_index < 0:
return NoneNode(self)
else:
- print("Get node", indices, node_index)
return Node(self, node_index)
def has_node(self, tuple indices) -> bool:
@@ -661,8 +661,6 @@ cdef int walk_head_nodes(vector[int]& output, const GraphC* graph, int node) nog
seen.insert(node)
i = 0
while i < output.size():
- with gil:
- print("Walk up from", output[i])
if seen.find(output[i]) == seen.end():
seen.insert(output[i])
get_head_nodes(output, graph, output[i])
diff --git a/spacy/tokens/span.pyi b/spacy/tokens/span.pyi
index 697051e81..9986a90e6 100644
--- a/spacy/tokens/span.pyi
+++ b/spacy/tokens/span.pyi
@@ -48,7 +48,8 @@ class Span:
label: Union[str, int] = ...,
vector: Optional[Floats1d] = ...,
vector_norm: Optional[float] = ...,
- kb_id: Optional[int] = ...,
+ kb_id: Union[str, int] = ...,
+ span_id: Union[str, int] = ...,
) -> None: ...
def __richcmp__(self, other: Span, op: int) -> bool: ...
def __hash__(self) -> int: ...
@@ -94,8 +95,8 @@ class Span:
self,
start_idx: int,
end_idx: int,
- label: int = ...,
- kb_id: int = ...,
+ label: Union[int, str] = ...,
+ kb_id: Union[int, str] = ...,
vector: Optional[Floats1d] = ...,
) -> Span: ...
@property
@@ -116,6 +117,7 @@ class Span:
end_char: int
label: int
kb_id: int
+ id: int
ent_id: int
ent_id_: str
@property
@@ -124,3 +126,4 @@ class Span:
def lemma_(self) -> str: ...
label_: str
kb_id_: str
+ id_: str
diff --git a/spacy/tokens/span.pyx b/spacy/tokens/span.pyx
index 4b0c724e5..99a5f43bd 100644
--- a/spacy/tokens/span.pyx
+++ b/spacy/tokens/span.pyx
@@ -80,17 +80,20 @@ cdef class Span:
return Underscore.span_extensions.pop(name)
def __cinit__(self, Doc doc, int start, int end, label=0, vector=None,
- vector_norm=None, kb_id=0):
+ vector_norm=None, kb_id=0, span_id=0):
"""Create a `Span` object from the slice `doc[start : end]`.
doc (Doc): The parent document.
start (int): The index of the first token of the span.
end (int): The index of the first token after the span.
- label (int or str): A label to attach to the Span, e.g. for named entities.
+ label (Union[int, str]): A label to attach to the Span, e.g. for named
+ entities.
vector (ndarray[ndim=1, dtype='float32']): A meaning representation
of the span.
vector_norm (float): The L2 norm of the span's vector representation.
- kb_id (uint64): An identifier from a Knowledge Base to capture the meaning of a named entity.
+ kb_id (Union[int, str]): An identifier from a Knowledge Base to capture
+ the meaning of a named entity.
+ span_id (Union[int, str]): An identifier to associate with the span.
DOCS: https://spacy.io/api/span#init
"""
@@ -101,6 +104,8 @@ cdef class Span:
label = doc.vocab.strings.add(label)
if isinstance(kb_id, str):
kb_id = doc.vocab.strings.add(kb_id)
+ if isinstance(span_id, str):
+ span_id = doc.vocab.strings.add(span_id)
if label not in doc.vocab.strings:
raise ValueError(Errors.E084.format(label=label))
@@ -112,6 +117,7 @@ cdef class Span:
self.c = SpanC(
label=label,
kb_id=kb_id,
+ id=span_id,
start=start,
end=end,
start_char=start_char,
@@ -126,8 +132,8 @@ cdef class Span:
return False
else:
return True
- self_tuple = (self.c.start_char, self.c.end_char, self.c.label, self.c.kb_id, self.doc)
- other_tuple = (other.c.start_char, other.c.end_char, other.c.label, other.c.kb_id, other.doc)
+ self_tuple = (self.c.start_char, self.c.end_char, self.c.label, self.c.kb_id, self.id, self.doc)
+ other_tuple = (other.c.start_char, other.c.end_char, other.c.label, other.c.kb_id, other.id, other.doc)
# <
if op == 0:
return self_tuple < other_tuple
@@ -148,7 +154,7 @@ cdef class Span:
return self_tuple >= other_tuple
def __hash__(self):
- return hash((self.doc, self.c.start_char, self.c.end_char, self.c.label, self.c.kb_id))
+ return hash((self.doc, self.c.start_char, self.c.end_char, self.c.label, self.c.kb_id, self.c.id))
def __len__(self):
"""Get the number of tokens in the span.
@@ -293,7 +299,7 @@ cdef class Span:
for ancestor in ancestors:
ancestor_i = ancestor.i - self.c.start
if ancestor_i in range(length):
- array[i, head_col] = ancestor_i - i
+ array[i, head_col] = numpy.int32(ancestor_i - i).astype(numpy.uint64)
# if there is no appropriate ancestor, define a new artificial root
value = array[i, head_col]
@@ -301,7 +307,7 @@ cdef class Span:
new_root = old_to_new_root.get(ancestor_i, None)
if new_root is not None:
# take the same artificial root as a previous token from the same sentence
- array[i, head_col] = new_root - i
+ array[i, head_col] = numpy.int32(new_root - i).astype(numpy.uint64)
else:
# set this token as the new artificial root
array[i, head_col] = 0
@@ -348,7 +354,8 @@ cdef class Span:
if self.vocab.vectors.n_keys == 0:
warnings.warn(Warnings.W007.format(obj="Span"))
if self.vector_norm == 0.0 or other.vector_norm == 0.0:
- warnings.warn(Warnings.W008.format(obj="Span"))
+ if not self.has_vector or not other.has_vector:
+ warnings.warn(Warnings.W008.format(obj="Span"))
return 0.0
vector = self.vector
xp = get_array_module(vector)
@@ -632,7 +639,7 @@ cdef class Span:
else:
return self.doc[root]
- def char_span(self, int start_idx, int end_idx, label=0, kb_id=0, vector=None):
+ def char_span(self, int start_idx, int end_idx, label=0, kb_id=0, vector=None, id=0):
"""Create a `Span` object from the slice `span.text[start : end]`.
start (int): The index of the first character of the span.
@@ -730,7 +737,7 @@ cdef class Span:
def __set__(self, int start):
if start < 0:
- raise IndexError("TODO")
+ raise IndexError(Errors.E1032.format(var="start", forbidden="< 0", value=start))
self.c.start = start
property end:
@@ -739,7 +746,7 @@ cdef class Span:
def __set__(self, int end):
if end < 0:
- raise IndexError("TODO")
+ raise IndexError(Errors.E1032.format(var="end", forbidden="< 0", value=end))
self.c.end = end
property start_char:
@@ -748,7 +755,7 @@ cdef class Span:
def __set__(self, int start_char):
if start_char < 0:
- raise IndexError("TODO")
+ raise IndexError(Errors.E1032.format(var="start_char", forbidden="< 0", value=start_char))
self.c.start_char = start_char
property end_char:
@@ -757,7 +764,7 @@ cdef class Span:
def __set__(self, int end_char):
if end_char < 0:
- raise IndexError("TODO")
+ raise IndexError(Errors.E1032.format(var="end_char", forbidden="< 0", value=end_char))
self.c.end_char = end_char
property label:
@@ -774,6 +781,13 @@ cdef class Span:
def __set__(self, attr_t kb_id):
self.c.kb_id = kb_id
+ property id:
+ def __get__(self):
+ return self.c.id
+
+ def __set__(self, attr_t id):
+ self.c.id = id
+
property ent_id:
"""RETURNS (uint64): The entity ID."""
def __get__(self):
@@ -812,13 +826,21 @@ cdef class Span:
self.label = self.doc.vocab.strings.add(label_)
property kb_id_:
- """RETURNS (str): The named entity's KB ID."""
+ """RETURNS (str): The span's KB ID."""
def __get__(self):
return self.doc.vocab.strings[self.kb_id]
def __set__(self, str kb_id_):
self.kb_id = self.doc.vocab.strings.add(kb_id_)
+ property id_:
+ """RETURNS (str): The span's ID."""
+ def __get__(self):
+ return self.doc.vocab.strings[self.id]
+
+ def __set__(self, str id_):
+ self.id = self.doc.vocab.strings.add(id_)
+
cdef int _count_words_to_root(const TokenC* token, int sent_length) except -1:
# Don't allow spaces to be the root, if there are
diff --git a/spacy/tokens/span_group.pyi b/spacy/tokens/span_group.pyi
index 26efc3ba0..0b4aa83aa 100644
--- a/spacy/tokens/span_group.pyi
+++ b/spacy/tokens/span_group.pyi
@@ -1,4 +1,4 @@
-from typing import Any, Dict, Iterable
+from typing import Any, Dict, Iterable, Optional
from .doc import Doc
from .span import Span
@@ -18,9 +18,11 @@ class SpanGroup:
def doc(self) -> Doc: ...
@property
def has_overlap(self) -> bool: ...
+ def __iter__(self): ...
def __len__(self) -> int: ...
def append(self, span: Span) -> None: ...
def extend(self, spans: Iterable[Span]) -> None: ...
def __getitem__(self, i: int) -> Span: ...
def to_bytes(self) -> bytes: ...
def from_bytes(self, bytes_data: bytes) -> SpanGroup: ...
+ def copy(self, doc: Optional[Doc] = ...) -> SpanGroup: ...
diff --git a/spacy/tokens/span_group.pyx b/spacy/tokens/span_group.pyx
index 6cfa75237..608dda283 100644
--- a/spacy/tokens/span_group.pyx
+++ b/spacy/tokens/span_group.pyx
@@ -1,10 +1,11 @@
+from typing import Iterable, Tuple, Union, Optional, TYPE_CHECKING
import weakref
import struct
+from copy import deepcopy
import srsly
from spacy.errors import Errors
from .span cimport Span
-from libc.stdint cimport uint64_t, uint32_t, int32_t
cdef class SpanGroup:
@@ -20,13 +21,13 @@ cdef class SpanGroup:
>>> doc.spans["errors"] = SpanGroup(
doc,
name="errors",
- spans=[doc[0:1], doc[2:4]],
+ spans=[doc[0:1], doc[1:3]],
attrs={"annotator": "matt"}
)
Construction 2
>>> doc = nlp("Their goi ng home")
- >>> doc.spans["errors"] = [doc[0:1], doc[2:4]]
+ >>> doc.spans["errors"] = [doc[0:1], doc[1:3]]
>>> assert isinstance(doc.spans["errors"], SpanGroup)
DOCS: https://spacy.io/api/spangroup
@@ -48,6 +49,8 @@ cdef class SpanGroup:
self.name = name
self.attrs = dict(attrs) if attrs is not None else {}
cdef Span span
+ if len(spans) :
+ self.c.reserve(len(spans))
for span in spans:
self.push_back(span.c)
@@ -89,6 +92,82 @@ cdef class SpanGroup:
"""
return self.c.size()
+ def __getitem__(self, int i) -> Span:
+ """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.
+
+ i (int): The item index.
+ RETURNS (Span): The span at the given index.
+
+ DOCS: https://spacy.io/api/spangroup#getitem
+ """
+ i = self._normalize_index(i)
+ return Span.cinit(self.doc, self.c[i])
+
+ def __delitem__(self, int i):
+ """Delete a span from the span group at index i.
+
+ i (int): The item index.
+
+ DOCS: https://spacy.io/api/spangroup#delitem
+ """
+ i = self._normalize_index(i)
+ self.c.erase(self.c.begin() + i - 1)
+
+ def __setitem__(self, int i, Span span):
+ """Set a span in the span group.
+
+ i (int): The item index.
+ span (Span): The span.
+
+ DOCS: https://spacy.io/api/spangroup#setitem
+ """
+ if span.doc is not self.doc:
+ raise ValueError(Errors.E855.format(obj="span"))
+
+ i = self._normalize_index(i)
+ self.c[i] = span.c
+
+ def __iadd__(self, other: Union[SpanGroup, Iterable["Span"]]) -> SpanGroup:
+ """Operator +=. Append a span group or spans to this group and return
+ the current span group.
+
+ other (Union[SpanGroup, Iterable["Span"]]): The SpanGroup or spans to
+ add.
+
+ RETURNS (SpanGroup): The current span group.
+
+ DOCS: https://spacy.io/api/spangroup#iadd
+ """
+ return self._concat(other, inplace=True)
+
+ def __add__(self, other: SpanGroup) -> SpanGroup:
+ """Operator +. Concatenate a span group with this group and return a
+ new span group.
+
+ other (SpanGroup): The SpanGroup to add.
+
+ RETURNS (SpanGroup): The concatenated SpanGroup.
+
+ DOCS: https://spacy.io/api/spangroup#add
+ """
+ # For Cython 0.x and __add__, you cannot rely on `self` as being `self`
+ # or being the right type, so both types need to be checked explicitly.
+ if isinstance(self, SpanGroup) and isinstance(other, SpanGroup):
+ return self._concat(other)
+ return NotImplemented
+
+ def __iter__(self):
+ """
+ Iterate over the spans in this SpanGroup.
+ YIELDS (Span): A span in this SpanGroup.
+
+ DOCS: https://spacy.io/api/spangroup#iter
+ """
+ for i in range(self.c.size()):
+ yield self[i]
+
def append(self, Span span):
"""Add a span to the group. The span must refer to the same Doc
object as the span group.
@@ -98,35 +177,18 @@ cdef class SpanGroup:
DOCS: https://spacy.io/api/spangroup#append
"""
if span.doc is not self.doc:
- raise ValueError("Cannot add span to group: refers to different Doc.")
+ raise ValueError(Errors.E855.format(obj="span"))
self.push_back(span.c)
- def extend(self, spans):
- """Add multiple spans to the group. All spans must refer to the same
- Doc object as the span group.
+ def extend(self, spans_or_span_group: Union[SpanGroup, Iterable["Span"]]):
+ """Add multiple spans or contents of another SpanGroup to the group.
+ All spans must refer to the same Doc object as the span group.
- spans (Iterable[Span]): The spans to add.
+ spans (Union[SpanGroup, Iterable["Span"]]): The spans to add.
DOCS: https://spacy.io/api/spangroup#extend
"""
- cdef Span span
- for span in spans:
- self.append(span)
-
- def __getitem__(self, int i):
- """Get a span from the group.
-
- i (int): The item index.
- RETURNS (Span): The span at the given index.
-
- DOCS: https://spacy.io/api/spangroup#getitem
- """
- cdef int size = self.c.size()
- if i < -size or i >= size:
- raise IndexError(f"list index {i} out of range")
- if i < 0:
- i += size
- return Span.cinit(self.doc, self.c[i])
+ self._concat(spans_or_span_group, inplace=True)
def to_bytes(self):
"""Serialize the SpanGroup's contents to a byte string.
@@ -136,6 +198,7 @@ cdef class SpanGroup:
DOCS: https://spacy.io/api/spangroup#to_bytes
"""
output = {"name": self.name, "attrs": self.attrs, "spans": []}
+ cdef int i
for i in range(self.c.size()):
span = self.c[i]
# The struct.pack here is probably overkill, but it might help if
@@ -187,3 +250,77 @@ cdef class SpanGroup:
cdef void push_back(self, SpanC span) nogil:
self.c.push_back(span)
+
+ def copy(self, doc: Optional["Doc"] = None) -> SpanGroup:
+ """Clones the span group.
+
+ doc (Doc): New reference document to which the copy is bound.
+ RETURNS (SpanGroup): A copy of the span group.
+
+ DOCS: https://spacy.io/api/spangroup#copy
+ """
+ if doc is None:
+ doc = self.doc
+ return SpanGroup(
+ doc,
+ name=self.name,
+ attrs=deepcopy(self.attrs),
+ spans=list(self),
+ )
+
+ def _concat(
+ self,
+ other: Union[SpanGroup, Iterable["Span"]],
+ *,
+ inplace: bool = False,
+ ) -> SpanGroup:
+ """Concatenates the current span group with the provided span group or
+ spans, either in place or creating a copy. Preserves the name of self,
+ updates attrs only with values that are not in self.
+
+ other (Union[SpanGroup, Iterable[Span]]): The spans to append.
+ inplace (bool): Indicates whether the operation should be performed in
+ place on the current span group.
+
+ RETURNS (SpanGroup): Either a new SpanGroup or the current SpanGroup
+ depending on the value of inplace.
+ """
+ cdef SpanGroup span_group = self if inplace else self.copy()
+ cdef SpanGroup other_group
+ cdef Span span
+
+ if isinstance(other, SpanGroup):
+ other_group = other
+ if other_group.doc is not self.doc:
+ raise ValueError(Errors.E855.format(obj="span group"))
+
+ other_attrs = deepcopy(other_group.attrs)
+ span_group.attrs.update({
+ key: value for key, value in other_attrs.items() \
+ if key not in span_group.attrs
+ })
+ if len(other_group):
+ span_group.c.reserve(span_group.c.size() + other_group.c.size())
+ span_group.c.insert(span_group.c.end(), other_group.c.begin(), other_group.c.end())
+ else:
+ if len(other):
+ span_group.c.reserve(self.c.size() + len(other))
+ for span in other:
+ if span.doc is not self.doc:
+ raise ValueError(Errors.E855.format(obj="span"))
+ span_group.c.push_back(span.c)
+
+ return span_group
+
+ def _normalize_index(self, int i) -> int:
+ """Checks list index boundaries and adjusts the index if negative.
+
+ i (int): The index.
+ RETURNS (int): The adjusted index.
+ """
+ cdef int length = self.c.size()
+ if i < -length or i >= length:
+ raise IndexError(Errors.E856.format(i=i, length=length))
+ if i < 0:
+ i += length
+ return i
diff --git a/spacy/tokens/token.pyx b/spacy/tokens/token.pyx
index d14930348..7fff6b162 100644
--- a/spacy/tokens/token.pyx
+++ b/spacy/tokens/token.pyx
@@ -206,7 +206,8 @@ cdef class Token:
if self.vocab.vectors.n_keys == 0:
warnings.warn(Warnings.W007.format(obj="Token"))
if self.vector_norm == 0 or other.vector_norm == 0:
- warnings.warn(Warnings.W008.format(obj="Token"))
+ if not self.has_vector or not other.has_vector:
+ warnings.warn(Warnings.W008.format(obj="Token"))
return 0.0
vector = self.vector
xp = get_array_module(vector)
diff --git a/spacy/training/__init__.py b/spacy/training/__init__.py
index a4feb01f4..71d1fa775 100644
--- a/spacy/training/__init__.py
+++ b/spacy/training/__init__.py
@@ -5,6 +5,7 @@ from .augment import dont_augment, orth_variants_augmenter # noqa: F401
from .iob_utils import iob_to_biluo, biluo_to_iob # noqa: F401
from .iob_utils import offsets_to_biluo_tags, biluo_tags_to_offsets # noqa: F401
from .iob_utils import biluo_tags_to_spans, tags_to_entities # noqa: F401
+from .iob_utils import split_bilu_label, remove_bilu_prefix # noqa: F401
from .gold_io import docs_to_json, read_json_file # noqa: F401
from .batchers import minibatch_by_padded_size, minibatch_by_words # noqa: F401
from .loggers import console_logger # noqa: F401
diff --git a/spacy/training/alignment.py b/spacy/training/alignment.py
index 3e3b60ca6..6d24714bf 100644
--- a/spacy/training/alignment.py
+++ b/spacy/training/alignment.py
@@ -1,31 +1,22 @@
from typing import List
-import numpy
-from thinc.types import Ragged
from dataclasses import dataclass
from .align import get_alignments
+from .alignment_array import AlignmentArray
@dataclass
class Alignment:
- x2y: Ragged
- y2x: Ragged
+ x2y: AlignmentArray
+ y2x: AlignmentArray
@classmethod
def from_indices(cls, x2y: List[List[int]], y2x: List[List[int]]) -> "Alignment":
- x2y = _make_ragged(x2y)
- y2x = _make_ragged(y2x)
+ x2y = AlignmentArray(x2y)
+ y2x = AlignmentArray(y2x)
return Alignment(x2y=x2y, y2x=y2x)
@classmethod
def from_strings(cls, A: List[str], B: List[str]) -> "Alignment":
x2y, y2x = get_alignments(A, B)
return Alignment.from_indices(x2y=x2y, y2x=y2x)
-
-
-def _make_ragged(indices):
- lengths = numpy.array([len(x) for x in indices], dtype="i")
- flat = []
- for x in indices:
- flat.extend(x)
- return Ragged(numpy.array(flat, dtype="i"), lengths)
diff --git a/spacy/training/alignment_array.pxd b/spacy/training/alignment_array.pxd
new file mode 100644
index 000000000..056f5bef3
--- /dev/null
+++ b/spacy/training/alignment_array.pxd
@@ -0,0 +1,7 @@
+from libcpp.vector cimport vector
+cimport numpy as np
+
+cdef class AlignmentArray:
+ cdef np.ndarray _data
+ cdef np.ndarray _lengths
+ cdef np.ndarray _starts_ends
diff --git a/spacy/training/alignment_array.pyx b/spacy/training/alignment_array.pyx
new file mode 100644
index 000000000..01e9d9bf8
--- /dev/null
+++ b/spacy/training/alignment_array.pyx
@@ -0,0 +1,74 @@
+from typing import List
+from ..errors import Errors
+import numpy
+from libc.stdint cimport int32_t
+
+
+cdef class AlignmentArray:
+ """AlignmentArray is similar to Thinc's Ragged with two simplfications:
+ indexing returns numpy arrays and this type can only be used for CPU arrays.
+ However, these changes make AlignmentArray more efficient for indexing in a
+ tight loop."""
+
+ __slots__ = []
+
+ def __init__(self, alignment: List[List[int]]):
+ cdef int data_len = 0
+ cdef int outer_len
+ cdef int idx
+
+ self._starts_ends = numpy.zeros(len(alignment) + 1, dtype='int32')
+ cdef int32_t* starts_ends_ptr = self._starts_ends.data
+
+ for idx, outer in enumerate(alignment):
+ outer_len = len(outer)
+ starts_ends_ptr[idx + 1] = starts_ends_ptr[idx] + outer_len
+ data_len += outer_len
+
+ self._lengths = None
+ self._data = numpy.empty(data_len, dtype="int32")
+
+ idx = 0
+ cdef int32_t* data_ptr = self._data.data
+
+ for outer in alignment:
+ for inner in outer:
+ data_ptr[idx] = inner
+ idx += 1
+
+ def __getitem__(self, idx):
+ starts = self._starts_ends[:-1]
+ ends = self._starts_ends[1:]
+ if isinstance(idx, int):
+ start = starts[idx]
+ end = ends[idx]
+ elif isinstance(idx, slice):
+ if not (idx.step is None or idx.step == 1):
+ raise ValueError(Errors.E1027)
+ start = starts[idx]
+ if len(start) == 0:
+ return self._data[0:0]
+ start = start[0]
+ end = ends[idx][-1]
+ else:
+ raise ValueError(Errors.E1028)
+
+ return self._data[start:end]
+
+ @property
+ def data(self):
+ return self._data
+
+ @property
+ def lengths(self):
+ if self._lengths is None:
+ self._lengths = self.ends - self.starts
+ return self._lengths
+
+ @property
+ def ends(self):
+ return self._starts_ends[1:]
+
+ @property
+ def starts(self):
+ return self._starts_ends[:-1]
diff --git a/spacy/training/augment.py b/spacy/training/augment.py
index 59a39c7ee..2fe8c24fb 100644
--- a/spacy/training/augment.py
+++ b/spacy/training/augment.py
@@ -3,10 +3,10 @@ from typing import Optional
import random
import itertools
from functools import partial
-from pydantic import BaseModel, StrictStr
from ..util import registry
from .example import Example
+from .iob_utils import split_bilu_label, _doc_to_biluo_tags_with_partial
if TYPE_CHECKING:
from ..language import Language # noqa: F401
@@ -62,6 +62,9 @@ def combined_augmenter(
if orth_variants and random.random() < orth_level:
raw_text = example.text
orig_dict = example.to_dict()
+ orig_dict["doc_annotation"]["entities"] = _doc_to_biluo_tags_with_partial(
+ example.reference
+ )
variant_text, variant_token_annot = make_orth_variants(
nlp,
raw_text,
@@ -128,6 +131,9 @@ def lower_casing_augmenter(
def make_lowercase_variant(nlp: "Language", example: Example):
example_dict = example.to_dict()
+ example_dict["doc_annotation"]["entities"] = _doc_to_biluo_tags_with_partial(
+ example.reference
+ )
doc = nlp.make_doc(example.text.lower())
example_dict["token_annotation"]["ORTH"] = [t.lower_ for t in example.reference]
return example.from_dict(doc, example_dict)
@@ -146,6 +152,9 @@ def orth_variants_augmenter(
else:
raw_text = example.text
orig_dict = example.to_dict()
+ orig_dict["doc_annotation"]["entities"] = _doc_to_biluo_tags_with_partial(
+ example.reference
+ )
variant_text, variant_token_annot = make_orth_variants(
nlp,
raw_text,
@@ -248,6 +257,9 @@ def make_whitespace_variant(
RETURNS (Example): Example with one additional space token.
"""
example_dict = example.to_dict()
+ example_dict["doc_annotation"]["entities"] = _doc_to_biluo_tags_with_partial(
+ example.reference
+ )
doc_dict = example_dict.get("doc_annotation", {})
token_dict = example_dict.get("token_annotation", {})
# returned unmodified if:
@@ -278,10 +290,8 @@ def make_whitespace_variant(
ent_prev = doc_dict["entities"][position - 1]
ent_next = doc_dict["entities"][position]
if "-" in ent_prev and "-" in ent_next:
- ent_iob_prev = ent_prev.split("-")[0]
- ent_type_prev = ent_prev.split("-", 1)[1]
- ent_iob_next = ent_next.split("-")[0]
- ent_type_next = ent_next.split("-", 1)[1]
+ ent_iob_prev, ent_type_prev = split_bilu_label(ent_prev)
+ ent_iob_next, ent_type_next = split_bilu_label(ent_next)
if (
ent_iob_prev in ("B", "I")
and ent_iob_next in ("I", "L")
diff --git a/spacy/training/example.pyx b/spacy/training/example.pyx
index d792c9bbf..95b0f0de9 100644
--- a/spacy/training/example.pyx
+++ b/spacy/training/example.pyx
@@ -9,11 +9,11 @@ from ..tokens.span import Span
from ..attrs import IDS
from .alignment import Alignment
from .iob_utils import biluo_to_iob, offsets_to_biluo_tags, doc_to_biluo_tags
-from .iob_utils import biluo_tags_to_spans
+from .iob_utils import biluo_tags_to_spans, remove_bilu_prefix
from ..errors import Errors, Warnings
from ..pipeline._parser_internals import nonproj
from ..tokens.token cimport MISSING_DEP
-from ..util import logger, to_ternary_int
+from ..util import logger, to_ternary_int, all_equal
cpdef Doc annotations_to_doc(vocab, tok_annot, doc_annot):
@@ -151,60 +151,137 @@ cdef class Example:
self._y_sig = y_sig
return self._cached_alignment
+
+ def _get_aligned_vectorized(self, align, gold_values):
+ # Fast path for Doc attributes/fields that are predominantly a single value,
+ # i.e., TAG, POS, MORPH.
+ x2y_single_toks = []
+ x2y_single_toks_i = []
+
+ x2y_multiple_toks = []
+ x2y_multiple_toks_i = []
+
+ # Gather indices of gold tokens aligned to the candidate tokens into two buckets.
+ # Bucket 1: All tokens that have a one-to-one alignment.
+ # Bucket 2: All tokens that have a one-to-many alignment.
+ for idx, token in enumerate(self.predicted):
+ aligned_gold_i = align[token.i]
+ aligned_gold_len = len(aligned_gold_i)
+
+ if aligned_gold_len == 1:
+ x2y_single_toks.append(aligned_gold_i.item())
+ x2y_single_toks_i.append(idx)
+ elif aligned_gold_len > 1:
+ x2y_multiple_toks.append(aligned_gold_i)
+ x2y_multiple_toks_i.append(idx)
+
+ # Map elements of the first bucket directly to the output array.
+ output = numpy.full(len(self.predicted), None)
+ output[x2y_single_toks_i] = gold_values[x2y_single_toks].squeeze()
+
+ # Collapse many-to-one alignments into one-to-one alignments if they
+ # share the same value. Map to None in all other cases.
+ for i in range(len(x2y_multiple_toks)):
+ aligned_gold_values = gold_values[x2y_multiple_toks[i]]
+
+ # If all aligned tokens have the same value, use it.
+ if all_equal(aligned_gold_values):
+ x2y_multiple_toks[i] = aligned_gold_values[0].item()
+ else:
+ x2y_multiple_toks[i] = None
+
+ output[x2y_multiple_toks_i] = x2y_multiple_toks
+
+ return output.tolist()
+
+
+ def _get_aligned_non_vectorized(self, align, gold_values):
+ # Slower path for fields that return multiple values (resulting
+ # in ragged arrays that cannot be vectorized trivially).
+ output = [None] * len(self.predicted)
+
+ for token in self.predicted:
+ aligned_gold_i = align[token.i]
+ values = gold_values[aligned_gold_i].ravel()
+ if len(values) == 1:
+ output[token.i] = values.item()
+ elif all_equal(values):
+ # If all aligned tokens have the same value, use it.
+ output[token.i] = values[0].item()
+
+ return output
+
+
def get_aligned(self, field, as_string=False):
"""Return an aligned array for a token attribute."""
align = self.alignment.x2y
+ gold_values = self.reference.to_array([field])
+
+ if len(gold_values.shape) == 1:
+ output = self._get_aligned_vectorized(align, gold_values)
+ else:
+ output = self._get_aligned_non_vectorized(align, gold_values)
vocab = self.reference.vocab
- gold_values = self.reference.to_array([field])
- output = [None] * len(self.predicted)
- for token in self.predicted:
- values = gold_values[align[token.i].dataXd]
- values = values.ravel()
- if len(values) == 0:
- output[token.i] = None
- elif len(values) == 1:
- output[token.i] = values[0]
- elif len(set(list(values))) == 1:
- # If all aligned tokens have the same value, use it.
- output[token.i] = values[0]
- else:
- output[token.i] = None
if as_string and field not in ["ENT_IOB", "SENT_START"]:
output = [vocab.strings[o] if o is not None else o for o in output]
+
return output
def get_aligned_parse(self, projectivize=True):
cand_to_gold = self.alignment.x2y
gold_to_cand = self.alignment.y2x
- aligned_heads = [None] * self.x.length
- aligned_deps = [None] * self.x.length
- has_deps = [token.has_dep() for token in self.y]
- has_heads = [token.has_head() for token in self.y]
heads = [token.head.i for token in self.y]
deps = [token.dep_ for token in self.y]
+
if projectivize:
proj_heads, proj_deps = nonproj.projectivize(heads, deps)
+ has_deps = [token.has_dep() for token in self.y]
+ has_heads = [token.has_head() for token in self.y]
+
# ensure that missing data remains missing
heads = [h if has_heads[i] else heads[i] for i, h in enumerate(proj_heads)]
deps = [d if has_deps[i] else deps[i] for i, d in enumerate(proj_deps)]
- for cand_i in range(self.x.length):
- if cand_to_gold.lengths[cand_i] == 1:
- gold_i = cand_to_gold[cand_i].dataXd[0, 0]
- if gold_to_cand.lengths[heads[gold_i]] == 1:
- aligned_heads[cand_i] = int(gold_to_cand[heads[gold_i]].dataXd[0, 0])
- aligned_deps[cand_i] = deps[gold_i]
- return aligned_heads, aligned_deps
+
+ # Select all candidate tokens that are aligned to a single gold token.
+ c2g_single_toks = numpy.where(cand_to_gold.lengths == 1)[0]
+
+ # Fetch all aligned gold token incides.
+ if c2g_single_toks.shape == cand_to_gold.lengths.shape:
+ # This the most likely case.
+ gold_i = cand_to_gold[:]
+ else:
+ gold_i = numpy.vectorize(lambda x: cand_to_gold[int(x)][0], otypes='i')(c2g_single_toks)
+
+ # Fetch indices of all gold heads for the aligned gold tokens.
+ heads = numpy.asarray(heads, dtype='i')
+ gold_head_i = heads[gold_i]
+
+ # Select all gold tokens that are heads of the previously selected
+ # gold tokens (and are aligned to a single candidate token).
+ g2c_len_heads = gold_to_cand.lengths[gold_head_i]
+ g2c_len_heads = numpy.where(g2c_len_heads == 1)[0]
+ g2c_i = numpy.vectorize(lambda x: gold_to_cand[int(x)][0], otypes='i')(gold_head_i[g2c_len_heads]).squeeze()
+
+ # Update head/dep alignments with the above.
+ aligned_heads = numpy.full((self.x.length), None)
+ aligned_heads[c2g_single_toks[g2c_len_heads]] = g2c_i
+
+ deps = numpy.asarray(deps)
+ aligned_deps = numpy.full((self.x.length), None)
+ aligned_deps[c2g_single_toks] = deps[gold_i]
+
+ return aligned_heads.tolist(), aligned_deps.tolist()
def get_aligned_sent_starts(self):
"""Get list of SENT_START attributes aligned to the predicted tokenization.
- If the reference has not sentence starts, return a list of None values.
+ If the reference does not have sentence starts, return a list of None values.
"""
if self.y.has_annotation("SENT_START"):
align = self.alignment.y2x
sent_starts = [False] * len(self.x)
for y_sent in self.y.sents:
- x_start = int(align[y_sent.start].dataXd[0])
+ x_start = int(align[y_sent.start][0])
sent_starts[x_start] = True
return sent_starts
else:
@@ -220,7 +297,7 @@ cdef class Example:
seen = set()
output = []
for span in spans:
- indices = align[span.start : span.end].data.ravel()
+ indices = align[span.start : span.end]
if not allow_overlap:
indices = [idx for idx in indices if idx not in seen]
if len(indices) >= 1:
@@ -256,11 +333,35 @@ cdef class Example:
x_ents, x_tags = self.get_aligned_ents_and_ner()
return x_tags
+ def get_matching_ents(self, check_label=True):
+ """Return entities that are shared between predicted and reference docs.
+
+ If `check_label` is True, entities must have matching labels to be
+ kept. Otherwise only the character indices need to match.
+ """
+ gold = {}
+ for ent in self.reference.ents:
+ gold[(ent.start_char, ent.end_char)] = ent.label
+
+ keep = []
+ for ent in self.predicted.ents:
+ key = (ent.start_char, ent.end_char)
+ if key not in gold:
+ continue
+
+ if check_label and ent.label != gold[key]:
+ continue
+
+ keep.append(ent)
+
+ return keep
+
def to_dict(self):
return {
"doc_annotation": {
"cats": dict(self.reference.cats),
"entities": doc_to_biluo_tags(self.reference),
+ "spans": self._spans_to_dict(),
"links": self._links_to_dict()
},
"token_annotation": {
@@ -276,6 +377,18 @@ cdef class Example:
}
}
+ def _spans_to_dict(self):
+ span_dict = {}
+ for key in self.reference.spans:
+ span_tuples = []
+ for span in self.reference.spans[key]:
+ span_tuple = (span.start_char, span.end_char, span.label_, span.kb_id_)
+ span_tuples.append(span_tuple)
+ span_dict[key] = span_tuples
+
+ return span_dict
+
+
def _links_to_dict(self):
links = {}
for ent in self.reference.ents:
@@ -293,7 +406,7 @@ cdef class Example:
seen_indices = set()
output = []
for y_sent in self.reference.sents:
- indices = align[y_sent.start : y_sent.end].data.ravel()
+ indices = align[y_sent.start : y_sent.end]
indices = [idx for idx in indices if idx not in seen_indices]
if indices:
x_sent = self.predicted[indices[0] : indices[-1] + 1]
@@ -330,26 +443,27 @@ def _annot2array(vocab, tok_annot, doc_annot):
if key not in IDS:
raise ValueError(Errors.E974.format(obj="token", key=key))
elif key in ["ORTH", "SPACY"]:
- pass
+ continue
elif key == "HEAD":
attrs.append(key)
- values.append([h-i if h is not None else 0 for i, h in enumerate(value)])
+ row = [h-i if h is not None else 0 for i, h in enumerate(value)]
elif key == "DEP":
attrs.append(key)
- values.append([vocab.strings.add(h) if h is not None else MISSING_DEP for h in value])
+ row = [vocab.strings.add(h) if h is not None else MISSING_DEP for h in value]
elif key == "SENT_START":
attrs.append(key)
- values.append([to_ternary_int(v) for v in value])
+ row = [to_ternary_int(v) for v in value]
elif key == "MORPH":
attrs.append(key)
- values.append([vocab.morphology.add(v) for v in value])
+ row = [vocab.morphology.add(v) for v in value]
else:
attrs.append(key)
if not all(isinstance(v, str) for v in value):
types = set([type(v) for v in value])
raise TypeError(Errors.E969.format(field=key, types=types)) from None
- values.append([vocab.strings.add(v) for v in value])
- array = numpy.asarray(values, dtype="uint64")
+ row = [vocab.strings.add(v) for v in value]
+ values.append([numpy.array(v, dtype=numpy.int32).astype(numpy.uint64) if v < 0 else v for v in row])
+ array = numpy.array(values, dtype=numpy.uint64)
return attrs, array.T
@@ -496,7 +610,7 @@ def _parse_ner_tags(biluo_or_offsets, vocab, words, spaces):
else:
ent_iobs.append(iob_tag.split("-")[0])
if iob_tag.startswith("I") or iob_tag.startswith("B"):
- ent_types.append(iob_tag.split("-", 1)[1])
+ ent_types.append(remove_bilu_prefix(iob_tag))
else:
ent_types.append("")
return ent_iobs, ent_types
diff --git a/spacy/training/initialize.py b/spacy/training/initialize.py
index b59288e38..6304e4a84 100644
--- a/spacy/training/initialize.py
+++ b/spacy/training/initialize.py
@@ -213,6 +213,7 @@ def convert_vectors(
for lex in nlp.vocab:
if lex.rank and lex.rank != OOV_RANK:
nlp.vocab.vectors.add(lex.orth, row=lex.rank) # type: ignore[attr-defined]
+ nlp.vocab.deduplicate_vectors()
else:
if vectors_loc:
logger.info(f"Reading vectors from {vectors_loc}")
@@ -239,6 +240,7 @@ def convert_vectors(
nlp.vocab.vectors = Vectors(
strings=nlp.vocab.strings, data=vectors_data, keys=vector_keys
)
+ nlp.vocab.deduplicate_vectors()
if name is None:
# TODO: Is this correct? Does this matter?
nlp.vocab.vectors.name = f"{nlp.meta['lang']}_{nlp.meta['name']}.vectors"
@@ -335,3 +337,5 @@ def ensure_shape(vectors_loc):
# store all the results in a list in memory
lines2 = open_file(vectors_loc)
yield from lines2
+ lines2.close()
+ lines.close()
diff --git a/spacy/training/iob_utils.py b/spacy/training/iob_utils.py
index 64492c2bc..0d4d246b0 100644
--- a/spacy/training/iob_utils.py
+++ b/spacy/training/iob_utils.py
@@ -1,4 +1,4 @@
-from typing import List, Dict, Tuple, Iterable, Union, Iterator
+from typing import List, Dict, Tuple, Iterable, Union, Iterator, cast
import warnings
from ..errors import Errors, Warnings
@@ -60,6 +60,14 @@ def doc_to_biluo_tags(doc: Doc, missing: str = "O"):
)
+def _doc_to_biluo_tags_with_partial(doc: Doc) -> List[str]:
+ ents = doc_to_biluo_tags(doc, missing="-")
+ for i, token in enumerate(doc):
+ if token.ent_iob == 2:
+ ents[i] = "O"
+ return ents
+
+
def offsets_to_biluo_tags(
doc: Doc, entities: Iterable[Tuple[int, int, Union[str, int]]], missing: str = "O"
) -> List[str]:
@@ -218,6 +226,14 @@ def tags_to_entities(tags: Iterable[str]) -> List[Tuple[str, int, int]]:
return entities
+def split_bilu_label(label: str) -> Tuple[str, str]:
+ return cast(Tuple[str, str], label.split("-", 1))
+
+
+def remove_bilu_prefix(label: str) -> str:
+ return label.split("-", 1)[1]
+
+
# Fallbacks to make backwards-compat easier
offsets_from_biluo_tags = biluo_tags_to_offsets
spans_from_biluo_tags = biluo_tags_to_spans
diff --git a/spacy/training/loggers.py b/spacy/training/loggers.py
index edd0f1959..7de31822e 100644
--- a/spacy/training/loggers.py
+++ b/spacy/training/loggers.py
@@ -1,10 +1,13 @@
-from typing import TYPE_CHECKING, Dict, Any, Tuple, Callable, List, Optional, IO
+from typing import TYPE_CHECKING, Dict, Any, Tuple, Callable, List, Optional, IO, Union
from wasabi import Printer
+from pathlib import Path
import tqdm
import sys
+import srsly
from ..util import registry
from ..errors import Errors
+from .. import util
if TYPE_CHECKING:
from ..language import Language # noqa: F401
@@ -23,31 +26,94 @@ def setup_table(
return final_cols, final_widths, ["r" for _ in final_widths]
-@registry.loggers("spacy.ConsoleLogger.v1")
-def console_logger(progress_bar: bool = False):
+# We cannot rename this method as it's directly imported
+# and used by external packages such as spacy-loggers.
+@registry.loggers("spacy.ConsoleLogger.v2")
+def console_logger(
+ progress_bar: bool = False,
+ console_output: bool = True,
+ output_file: Optional[Union[str, Path]] = None,
+):
+ """The ConsoleLogger.v2 prints out training logs in the console and/or saves them to a jsonl file.
+ progress_bar (bool): Whether the logger should print a progress bar tracking the steps till the next evaluation pass.
+ console_output (bool): Whether the logger should print the logs on the console.
+ output_file (Optional[Union[str, Path]]): The file to save the training logs to.
+ """
+ return console_logger_v3(
+ progress_bar=None if progress_bar is False else "eval",
+ console_output=console_output,
+ output_file=output_file,
+ )
+
+
+@registry.loggers("spacy.ConsoleLogger.v3")
+def console_logger_v3(
+ progress_bar: Optional[str] = None,
+ console_output: bool = True,
+ output_file: Optional[Union[str, Path]] = None,
+):
+ """The ConsoleLogger.v3 prints out training logs in the console and/or saves them to a jsonl file.
+ progress_bar (Optional[str]): Type of progress bar to show in the console. Allowed values:
+ train - Tracks the number of steps from the beginning of training until the full training run is complete (training.max_steps is reached).
+ eval - Tracks the number of steps between the previous and next evaluation (training.eval_frequency is reached).
+ console_output (bool): Whether the logger should print the logs on the console.
+ output_file (Optional[Union[str, Path]]): The file to save the training logs to.
+ """
+ _log_exist = False
+ if output_file:
+ output_file = util.ensure_path(output_file) # type: ignore
+ if output_file.exists(): # type: ignore
+ _log_exist = True
+ if not output_file.parents[0].exists(): # type: ignore
+ output_file.parents[0].mkdir(parents=True) # type: ignore
+
def setup_printer(
nlp: "Language", stdout: IO = sys.stdout, stderr: IO = sys.stderr
) -> Tuple[Callable[[Optional[Dict[str, Any]]], None], Callable[[], None]]:
write = lambda text: print(text, file=stdout, flush=True)
msg = Printer(no_print=True)
+
+ nonlocal output_file
+ output_stream = None
+ if _log_exist:
+ write(
+ msg.warn(
+ f"Saving logs is disabled because {output_file} already exists."
+ )
+ )
+ output_file = None
+ elif output_file:
+ write(msg.info(f"Saving results to {output_file}"))
+ output_stream = open(output_file, "w", encoding="utf-8")
+
# ensure that only trainable components are logged
logged_pipes = [
name
for name, proc in nlp.pipeline
if hasattr(proc, "is_trainable") and proc.is_trainable
]
+ max_steps = nlp.config["training"]["max_steps"]
eval_frequency = nlp.config["training"]["eval_frequency"]
score_weights = nlp.config["training"]["score_weights"]
score_cols = [col for col, value in score_weights.items() if value is not None]
loss_cols = [f"Loss {pipe}" for pipe in logged_pipes]
- spacing = 2
- table_header, table_widths, table_aligns = setup_table(
- cols=["E", "#"] + loss_cols + score_cols + ["Score"],
- widths=[3, 6] + [8 for _ in loss_cols] + [6 for _ in score_cols] + [6],
- )
- write(msg.row(table_header, widths=table_widths, spacing=spacing))
- write(msg.row(["-" * width for width in table_widths], spacing=spacing))
+
+ if console_output:
+ spacing = 2
+ table_header, table_widths, table_aligns = setup_table(
+ cols=["E", "#"] + loss_cols + score_cols + ["Score"],
+ widths=[3, 6] + [8 for _ in loss_cols] + [6 for _ in score_cols] + [6],
+ )
+ write(msg.row(table_header, widths=table_widths, spacing=spacing))
+ write(msg.row(["-" * width for width in table_widths], spacing=spacing))
progress = None
+ expected_progress_types = ("train", "eval")
+ if progress_bar is not None and progress_bar not in expected_progress_types:
+ raise ValueError(
+ Errors.E1048.format(
+ unexpected=progress_bar, expected=expected_progress_types
+ )
+ )
def log_step(info: Optional[Dict[str, Any]]) -> None:
nonlocal progress
@@ -57,12 +123,15 @@ def console_logger(progress_bar: bool = False):
if progress is not None:
progress.update(1)
return
- losses = [
- "{0:.2f}".format(float(info["losses"][pipe_name]))
- for pipe_name in logged_pipes
- ]
+
+ losses = []
+ log_losses = {}
+ for pipe_name in logged_pipes:
+ losses.append("{0:.2f}".format(float(info["losses"][pipe_name])))
+ log_losses[pipe_name] = float(info["losses"][pipe_name])
scores = []
+ log_scores = {}
for col in score_cols:
score = info["other_scores"].get(col, 0.0)
try:
@@ -73,6 +142,7 @@ def console_logger(progress_bar: bool = False):
if col != "speed":
score *= 100
scores.append("{0:.2f}".format(score))
+ log_scores[str(col)] = score
data = (
[info["epoch"], info["step"]]
@@ -80,20 +150,48 @@ def console_logger(progress_bar: bool = False):
+ scores
+ ["{0:.2f}".format(float(info["score"]))]
)
+
+ if output_stream:
+ # Write to log file per log_step
+ log_data = {
+ "epoch": info["epoch"],
+ "step": info["step"],
+ "losses": log_losses,
+ "scores": log_scores,
+ "score": float(info["score"]),
+ }
+ output_stream.write(srsly.json_dumps(log_data) + "\n")
+
if progress is not None:
progress.close()
- write(
- msg.row(data, widths=table_widths, aligns=table_aligns, spacing=spacing)
- )
- if progress_bar:
- # Set disable=None, so that it disables on non-TTY
- progress = tqdm.tqdm(
- total=eval_frequency, disable=None, leave=False, file=stderr
+ if console_output:
+ write(
+ msg.row(
+ data, widths=table_widths, aligns=table_aligns, spacing=spacing
+ )
)
- progress.set_description(f"Epoch {info['epoch']+1}")
+ if progress_bar:
+ if progress_bar == "train":
+ total = max_steps
+ desc = f"Last Eval Epoch: {info['epoch']}"
+ initial = info["step"]
+ else:
+ total = eval_frequency
+ desc = f"Epoch {info['epoch']+1}"
+ initial = 0
+ # Set disable=None, so that it disables on non-TTY
+ progress = tqdm.tqdm(
+ total=total,
+ disable=None,
+ leave=False,
+ file=stderr,
+ initial=initial,
+ )
+ progress.set_description(desc)
def finalize() -> None:
- pass
+ if output_stream:
+ output_stream.close()
return log_step, finalize
diff --git a/spacy/training/loop.py b/spacy/training/loop.py
index 06372cbb0..885257772 100644
--- a/spacy/training/loop.py
+++ b/spacy/training/loop.py
@@ -59,6 +59,7 @@ def train(
batcher = T["batcher"]
train_logger = T["logger"]
before_to_disk = create_before_to_disk_callback(T["before_to_disk"])
+ before_update = T["before_update"]
# Helper function to save checkpoints. This is a closure for convenience,
# to avoid passing in all the args all the time.
@@ -89,6 +90,7 @@ def train(
eval_frequency=T["eval_frequency"],
exclude=frozen_components,
annotating_components=annotating_components,
+ before_update=before_update,
)
clean_output_dir(output_path)
stdout.write(msg.info(f"Pipeline: {nlp.pipe_names}") + "\n")
@@ -150,6 +152,7 @@ def train_while_improving(
max_steps: int,
exclude: List[str],
annotating_components: List[str],
+ before_update: Optional[Callable[["Language", Dict[str, Any]], None]],
):
"""Train until an evaluation stops improving. Works as a generator,
with each iteration yielding a tuple `(batch, info, is_best_checkpoint)`,
@@ -198,6 +201,9 @@ def train_while_improving(
words_seen = 0
start_time = timer()
for step, (epoch, batch) in enumerate(train_data):
+ if before_update:
+ before_update_args = {"step": step, "epoch": epoch}
+ before_update(nlp, before_update_args)
dropout = next(dropouts) # type: ignore
for subbatch in subdivide_batch(batch, accumulate_gradient):
nlp.update(
diff --git a/spacy/util.py b/spacy/util.py
index 2a8b9f5cc..8bf8fb1b0 100644
--- a/spacy/util.py
+++ b/spacy/util.py
@@ -1,6 +1,6 @@
-from typing import List, Mapping, NoReturn, Union, Dict, Any, Set
+from typing import List, Mapping, NoReturn, Union, Dict, Any, Set, cast
from typing import Optional, Iterable, Callable, Tuple, Type
-from typing import Iterator, Type, Pattern, Generator, TYPE_CHECKING
+from typing import Iterator, Pattern, Generator, TYPE_CHECKING
from types import ModuleType
import os
import importlib
@@ -12,7 +12,6 @@ from thinc.api import NumpyOps, get_current_ops, Adam, Config, Optimizer
from thinc.api import ConfigValidationError, Model
import functools
import itertools
-import numpy.random
import numpy
import srsly
import catalogue
@@ -32,6 +31,7 @@ import shlex
import inspect
import pkgutil
import logging
+import socket
try:
import cupy.random
@@ -52,8 +52,7 @@ from . import about
if TYPE_CHECKING:
# This lets us add type hints for mypy etc. without causing circular imports
- from .language import Language # noqa: F401
- from .pipeline import Pipe # noqa: F401
+ from .language import Language, PipeCallable # noqa: F401
from .tokens import Doc, Span # noqa: F401
from .vocab import Vocab # noqa: F401
@@ -68,7 +67,6 @@ LEXEME_NORM_LANGS = ["cs", "da", "de", "el", "en", "id", "lb", "mk", "pt", "ru",
CONFIG_SECTION_ORDER = ["paths", "variables", "system", "nlp", "components", "corpora", "training", "pretraining", "initialize"]
# fmt: on
-
logger = logging.getLogger("spacy")
logger_stream_handler = logging.StreamHandler()
logger_stream_handler.setFormatter(
@@ -294,7 +292,7 @@ def find_matching_language(lang: str) -> Optional[str]:
# Find out which language modules we have
possible_languages = []
- for modinfo in pkgutil.iter_modules(spacy.lang.__path__): # type: ignore
+ for modinfo in pkgutil.iter_modules(spacy.lang.__path__): # type: ignore[attr-defined]
code = modinfo.name
if code == "xx":
# Temporarily make 'xx' into a valid language code
@@ -391,15 +389,21 @@ def get_module_path(module: ModuleType) -> Path:
"""
if not hasattr(module, "__module__"):
raise ValueError(Errors.E169.format(module=repr(module)))
- return Path(sys.modules[module.__module__].__file__).parent
+ file_path = Path(cast(os.PathLike, sys.modules[module.__module__].__file__))
+ return file_path.parent
+
+
+# Default value for passed enable/disable values.
+_DEFAULT_EMPTY_PIPES = SimpleFrozenList()
def load_model(
name: Union[str, Path],
*,
vocab: Union["Vocab", bool] = True,
- disable: Iterable[str] = SimpleFrozenList(),
- exclude: Iterable[str] = SimpleFrozenList(),
+ disable: Union[str, Iterable[str]] = _DEFAULT_EMPTY_PIPES,
+ enable: Union[str, Iterable[str]] = _DEFAULT_EMPTY_PIPES,
+ exclude: Union[str, Iterable[str]] = _DEFAULT_EMPTY_PIPES,
config: Union[Dict[str, Any], Config] = SimpleFrozenDict(),
) -> "Language":
"""Load a model from a package or data path.
@@ -407,12 +411,20 @@ def load_model(
name (str): Package name or model path.
vocab (Vocab / True): Optional vocab to pass in on initialization. If True,
a new Vocab object will be created.
- disable (Iterable[str]): Names of pipeline components to disable.
+ disable (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to disable.
+ enable (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to enable. All others will be disabled.
+ exclude (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to exclude.
config (Dict[str, Any] / Config): Config overrides as nested dict or dict
keyed by section values in dot notation.
RETURNS (Language): The loaded nlp object.
"""
- kwargs = {"vocab": vocab, "disable": disable, "exclude": exclude, "config": config}
+ kwargs = {
+ "vocab": vocab,
+ "disable": disable,
+ "enable": enable,
+ "exclude": exclude,
+ "config": config,
+ }
if isinstance(name, str): # name or string path
if name.startswith("blank:"): # shortcut for blank model
return get_lang_class(name.replace("blank:", ""))()
@@ -431,8 +443,9 @@ def load_model_from_package(
name: str,
*,
vocab: Union["Vocab", bool] = True,
- disable: Iterable[str] = SimpleFrozenList(),
- exclude: Iterable[str] = SimpleFrozenList(),
+ disable: Union[str, Iterable[str]] = _DEFAULT_EMPTY_PIPES,
+ enable: Union[str, Iterable[str]] = _DEFAULT_EMPTY_PIPES,
+ exclude: Union[str, Iterable[str]] = _DEFAULT_EMPTY_PIPES,
config: Union[Dict[str, Any], Config] = SimpleFrozenDict(),
) -> "Language":
"""Load a model from an installed package.
@@ -440,17 +453,19 @@ def load_model_from_package(
name (str): The package name.
vocab (Vocab / True): Optional vocab to pass in on initialization. If True,
a new Vocab object will be created.
- disable (Iterable[str]): Names of pipeline components to disable. Disabled
+ disable (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to disable. Disabled
pipes will be loaded but they won't be run unless you explicitly
enable them by calling nlp.enable_pipe.
- exclude (Iterable[str]): Names of pipeline components to exclude. Excluded
+ enable (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to enable. All other
+ pipes will be disabled (and can be enabled using `nlp.enable_pipe`).
+ exclude (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to exclude. Excluded
components won't be loaded.
config (Dict[str, Any] / Config): Config overrides as nested dict or dict
keyed by section values in dot notation.
RETURNS (Language): The loaded nlp object.
"""
cls = importlib.import_module(name)
- return cls.load(vocab=vocab, disable=disable, exclude=exclude, config=config) # type: ignore[attr-defined]
+ return cls.load(vocab=vocab, disable=disable, enable=enable, exclude=exclude, config=config) # type: ignore[attr-defined]
def load_model_from_path(
@@ -458,8 +473,9 @@ def load_model_from_path(
*,
meta: Optional[Dict[str, Any]] = None,
vocab: Union["Vocab", bool] = True,
- disable: Iterable[str] = SimpleFrozenList(),
- exclude: Iterable[str] = SimpleFrozenList(),
+ disable: Union[str, Iterable[str]] = _DEFAULT_EMPTY_PIPES,
+ enable: Union[str, Iterable[str]] = _DEFAULT_EMPTY_PIPES,
+ exclude: Union[str, Iterable[str]] = _DEFAULT_EMPTY_PIPES,
config: Union[Dict[str, Any], Config] = SimpleFrozenDict(),
) -> "Language":
"""Load a model from a data directory path. Creates Language class with
@@ -469,10 +485,12 @@ def load_model_from_path(
meta (Dict[str, Any]): Optional model meta.
vocab (Vocab / True): Optional vocab to pass in on initialization. If True,
a new Vocab object will be created.
- disable (Iterable[str]): Names of pipeline components to disable. Disabled
+ disable (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to disable. Disabled
pipes will be loaded but they won't be run unless you explicitly
enable them by calling nlp.enable_pipe.
- exclude (Iterable[str]): Names of pipeline components to exclude. Excluded
+ enable (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to enable. All other
+ pipes will be disabled (and can be enabled using `nlp.enable_pipe`).
+ exclude (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to exclude. Excluded
components won't be loaded.
config (Dict[str, Any] / Config): Config overrides as nested dict or dict
keyed by section values in dot notation.
@@ -485,16 +503,25 @@ def load_model_from_path(
config_path = model_path / "config.cfg"
overrides = dict_to_dot(config)
config = load_config(config_path, overrides=overrides)
- nlp = load_model_from_config(config, vocab=vocab, disable=disable, exclude=exclude)
+ nlp = load_model_from_config(
+ config,
+ vocab=vocab,
+ disable=disable,
+ enable=enable,
+ exclude=exclude,
+ meta=meta,
+ )
return nlp.from_disk(model_path, exclude=exclude, overrides=overrides)
def load_model_from_config(
config: Union[Dict[str, Any], Config],
*,
+ meta: Dict[str, Any] = SimpleFrozenDict(),
vocab: Union["Vocab", bool] = True,
- disable: Iterable[str] = SimpleFrozenList(),
- exclude: Iterable[str] = SimpleFrozenList(),
+ disable: Union[str, Iterable[str]] = _DEFAULT_EMPTY_PIPES,
+ enable: Union[str, Iterable[str]] = _DEFAULT_EMPTY_PIPES,
+ exclude: Union[str, Iterable[str]] = _DEFAULT_EMPTY_PIPES,
auto_fill: bool = False,
validate: bool = True,
) -> "Language":
@@ -505,10 +532,12 @@ def load_model_from_config(
meta (Dict[str, Any]): Optional model meta.
vocab (Vocab / True): Optional vocab to pass in on initialization. If True,
a new Vocab object will be created.
- disable (Iterable[str]): Names of pipeline components to disable. Disabled
+ disable (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to disable. Disabled
pipes will be loaded but they won't be run unless you explicitly
enable them by calling nlp.enable_pipe.
- exclude (Iterable[str]): Names of pipeline components to exclude. Excluded
+ enable (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to enable. All other
+ pipes will be disabled (and can be enabled using `nlp.enable_pipe`).
+ exclude (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to exclude. Excluded
components won't be loaded.
auto_fill (bool): Whether to auto-fill config with missing defaults.
validate (bool): Whether to show config validation errors.
@@ -526,9 +555,11 @@ def load_model_from_config(
config,
vocab=vocab,
disable=disable,
+ enable=enable,
exclude=exclude,
auto_fill=auto_fill,
validate=validate,
+ meta=meta,
)
return nlp
@@ -588,8 +619,9 @@ def load_model_from_init_py(
init_file: Union[Path, str],
*,
vocab: Union["Vocab", bool] = True,
- disable: Iterable[str] = SimpleFrozenList(),
- exclude: Iterable[str] = SimpleFrozenList(),
+ disable: Union[str, Iterable[str]] = _DEFAULT_EMPTY_PIPES,
+ enable: Union[str, Iterable[str]] = _DEFAULT_EMPTY_PIPES,
+ exclude: Union[str, Iterable[str]] = _DEFAULT_EMPTY_PIPES,
config: Union[Dict[str, Any], Config] = SimpleFrozenDict(),
) -> "Language":
"""Helper function to use in the `load()` method of a model package's
@@ -597,10 +629,12 @@ def load_model_from_init_py(
vocab (Vocab / True): Optional vocab to pass in on initialization. If True,
a new Vocab object will be created.
- disable (Iterable[str]): Names of pipeline components to disable. Disabled
+ disable (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to disable. Disabled
pipes will be loaded but they won't be run unless you explicitly
enable them by calling nlp.enable_pipe.
- exclude (Iterable[str]): Names of pipeline components to exclude. Excluded
+ enable (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to enable. All other
+ pipes will be disabled (and can be enabled using `nlp.enable_pipe`).
+ exclude (Union[str, Iterable[str]]): Name(s) of pipeline component(s) to exclude. Excluded
components won't be loaded.
config (Dict[str, Any] / Config): Config overrides as nested dict or dict
keyed by section values in dot notation.
@@ -617,6 +651,7 @@ def load_model_from_init_py(
vocab=vocab,
meta=meta,
disable=disable,
+ enable=enable,
exclude=exclude,
config=config,
)
@@ -763,6 +798,15 @@ def get_model_lower_version(constraint: str) -> Optional[str]:
return None
+def is_prerelease_version(version: str) -> bool:
+ """Check whether a version is a prerelease version.
+
+ version (str): The version, e.g. "3.0.0.dev1".
+ RETURNS (bool): Whether the version is a prerelease version.
+ """
+ return Version(version).is_prerelease
+
+
def get_base_version(version: str) -> str:
"""Generate the base version without any prerelease identifiers.
@@ -874,7 +918,7 @@ def get_package_path(name: str) -> Path:
# Here we're importing the module just to find it. This is worryingly
# indirect, but it's otherwise very difficult to find the package.
pkg = importlib.import_module(name)
- return Path(pkg.__file__).parent
+ return Path(cast(Union[str, os.PathLike], pkg.__file__)).parent
def replace_model_node(model: Model, target: Model, replacement: Model) -> None:
@@ -1237,6 +1281,15 @@ def filter_spans(spans: Iterable["Span"]) -> List["Span"]:
return result
+def filter_chain_spans(*spans: Iterable["Span"]) -> List["Span"]:
+ return filter_spans(itertools.chain(*spans))
+
+
+@registry.misc("spacy.first_longest_spans_filter.v1")
+def make_first_longest_spans_filter():
+ return filter_chain_spans
+
+
def to_bytes(getters: Dict[str, Callable[[], bytes]], exclude: Iterable[str]) -> bytes:
return srsly.msgpack_dumps(to_dict(getters, exclude))
@@ -1589,9 +1642,11 @@ def check_bool_env_var(env_var: str) -> bool:
def _pipe(
docs: Iterable["Doc"],
- proc: "Pipe",
+ proc: "PipeCallable",
name: str,
- default_error_handler: Callable[[str, "Pipe", List["Doc"], Exception], NoReturn],
+ default_error_handler: Callable[
+ [str, "PipeCallable", List["Doc"], Exception], NoReturn
+ ],
kwargs: Mapping[str, Any],
) -> Iterator["Doc"]:
if hasattr(proc, "pipe"):
@@ -1671,7 +1726,61 @@ def packages_distributions() -> Dict[str, List[str]]:
it's not available in the builtin importlib.metadata.
"""
pkg_to_dist = defaultdict(list)
- for dist in importlib_metadata.distributions(): # type: ignore[attr-defined]
+ for dist in importlib_metadata.distributions():
for pkg in (dist.read_text("top_level.txt") or "").split():
pkg_to_dist[pkg].append(dist.metadata["Name"])
return dict(pkg_to_dist)
+
+
+def all_equal(iterable):
+ """Return True if all the elements are equal to each other
+ (or if the input is an empty sequence), False otherwise."""
+ g = itertools.groupby(iterable)
+ return next(g, True) and not next(g, False)
+
+
+def _is_port_in_use(port: int, host: str = "localhost") -> bool:
+ """Check if 'host:port' is in use. Return True if it is, False otherwise.
+
+ port (int): the port to check
+ host (str): the host to check (default "localhost")
+ RETURNS (bool): Whether 'host:port' is in use.
+ """
+ s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+ try:
+ s.bind((host, port))
+ return False
+ except socket.error:
+ return True
+ finally:
+ s.close()
+
+
+def find_available_port(start: int, host: str, auto_select: bool = False) -> int:
+ """Given a starting port and a host, handle finding a port.
+
+ If `auto_select` is False, a busy port will raise an error.
+
+ If `auto_select` is True, the next free higher port will be used.
+
+ start (int): the port to start looking from
+ host (str): the host to find a port on
+ auto_select (bool): whether to automatically select a new port if the given port is busy (default False)
+ RETURNS (int): The port to use.
+ """
+ if not _is_port_in_use(start, host):
+ return start
+
+ port = start
+ if not auto_select:
+ raise ValueError(Errors.E1050.format(port=port))
+
+ while _is_port_in_use(port, host) and port < 65535:
+ port += 1
+
+ if port == 65535 and _is_port_in_use(port, host):
+ raise ValueError(Errors.E1049.format(host=host))
+
+ # if we get here, the port changed
+ warnings.warn(Warnings.W124.format(host=host, port=start, serve_port=port))
+ return port
diff --git a/spacy/vectors.pyx b/spacy/vectors.pyx
index 2b1ea764b..be0f6db09 100644
--- a/spacy/vectors.pyx
+++ b/spacy/vectors.pyx
@@ -243,6 +243,15 @@ cdef class Vectors:
else:
return key in self.key2row
+ def __eq__(self, other):
+ # Check for equality, with faster checks first
+ return (
+ self.shape == other.shape
+ and self.key2row == other.key2row
+ and self.to_bytes(exclude=["strings"])
+ == other.to_bytes(exclude=["strings"])
+ )
+
def resize(self, shape, inplace=False):
"""Resize the underlying vectors array. If inplace=True, the memory
is reallocated. This may cause other references to the data to become
@@ -336,10 +345,10 @@ cdef class Vectors:
xp = get_array_module(self.data)
if key is not None:
key = get_string_id(key)
- return self.key2row.get(key, -1)
+ return self.key2row.get(int(key), -1)
elif keys is not None:
keys = [get_string_id(key) for key in keys]
- rows = [self.key2row.get(key, -1.) for key in keys]
+ rows = [self.key2row.get(int(key), -1) for key in keys]
return xp.asarray(rows, dtype="i")
else:
row2key = {row: key for key, row in self.key2row.items()}
@@ -565,8 +574,9 @@ cdef class Vectors:
# the source of numpy.save indicates that the file object is closed after use.
# but it seems that somehow this does not happen, as ResourceWarnings are raised here.
# in order to not rely on this, wrap in context manager.
+ ops = get_current_ops()
with path.open("wb") as _file:
- save_array(self.data, _file)
+ save_array(ops.to_numpy(self.data, byte_order="<"), _file)
serializers = {
"strings": lambda p: self.strings.to_disk(p.with_suffix(".json")),
@@ -602,6 +612,7 @@ cdef class Vectors:
ops = get_current_ops()
if path.exists():
self.data = ops.xp.load(str(path))
+ self.to_ops(ops)
def load_settings(path):
if path.exists():
@@ -631,7 +642,8 @@ cdef class Vectors:
if hasattr(self.data, "to_bytes"):
return self.data.to_bytes()
else:
- return srsly.msgpack_dumps(self.data)
+ ops = get_current_ops()
+ return srsly.msgpack_dumps(ops.to_numpy(self.data, byte_order="<"))
serializers = {
"strings": lambda: self.strings.to_bytes(),
@@ -656,6 +668,8 @@ cdef class Vectors:
else:
xp = get_array_module(self.data)
self.data = xp.asarray(srsly.msgpack_loads(b))
+ ops = get_current_ops()
+ self.to_ops(ops)
deserializers = {
"strings": lambda b: self.strings.from_bytes(b),
diff --git a/spacy/vocab.pyi b/spacy/vocab.pyi
index 713e85c01..4cc359c47 100644
--- a/spacy/vocab.pyi
+++ b/spacy/vocab.pyi
@@ -46,6 +46,7 @@ class Vocab:
def reset_vectors(
self, *, width: Optional[int] = ..., shape: Optional[int] = ...
) -> None: ...
+ def deduplicate_vectors(self) -> None: ...
def prune_vectors(self, nr_row: int, batch_size: int = ...) -> Dict[str, float]: ...
def get_vector(
self,
diff --git a/spacy/vocab.pyx b/spacy/vocab.pyx
index badd291ed..27f8e5f98 100644
--- a/spacy/vocab.pyx
+++ b/spacy/vocab.pyx
@@ -1,6 +1,7 @@
# cython: profile=True
from libc.string cimport memcpy
+import numpy
import srsly
from thinc.api import get_array_module, get_current_ops
import functools
@@ -297,6 +298,33 @@ cdef class Vocab:
width = width if width is not None else self.vectors.shape[1]
self.vectors = Vectors(strings=self.strings, shape=(self.vectors.shape[0], width))
+ def deduplicate_vectors(self):
+ if self.vectors.mode != VectorsMode.default:
+ raise ValueError(Errors.E858.format(
+ mode=self.vectors.mode,
+ alternative=""
+ ))
+ ops = get_current_ops()
+ xp = get_array_module(self.vectors.data)
+ filled = xp.asarray(
+ sorted(list({row for row in self.vectors.key2row.values()}))
+ )
+ # deduplicate data and remap keys
+ data = numpy.unique(ops.to_numpy(self.vectors.data[filled]), axis=0)
+ data = ops.asarray(data)
+ if data.shape == self.vectors.data.shape:
+ # nothing to deduplicate
+ return
+ row_by_bytes = {row.tobytes(): i for i, row in enumerate(data)}
+ key2row = {
+ key: row_by_bytes[self.vectors.data[row].tobytes()]
+ for key, row in self.vectors.key2row.items()
+ }
+ # replace vectors with deduplicated version
+ self.vectors = Vectors(strings=self.strings, data=data, name=self.vectors.name)
+ for key, row in key2row.items():
+ self.vectors.add(key, row=row)
+
def prune_vectors(self, nr_row, batch_size=1024):
"""Reduce the current vector table to `nr_row` unique entries. Words
mapped to the discarded vectors will be remapped to the closest vector
@@ -325,7 +353,10 @@ cdef class Vocab:
DOCS: https://spacy.io/api/vocab#prune_vectors
"""
if self.vectors.mode != VectorsMode.default:
- raise ValueError(Errors.E866)
+ raise ValueError(Errors.E858.format(
+ mode=self.vectors.mode,
+ alternative=""
+ ))
ops = get_current_ops()
xp = get_array_module(self.vectors.data)
# Make sure all vectors are in the vocab
@@ -354,8 +385,9 @@ cdef class Vocab:
def get_vector(self, orth):
"""Retrieve a vector for a word in the vocabulary. Words can be looked
- up by string or int ID. If no vectors data is loaded, ValueError is
- raised.
+ up by string or int ID. If the current vectors do not contain an entry
+ for the word, a 0-vector with the same number of dimensions as the
+ current vectors is returned.
orth (int / unicode): The hash value of a word, or its unicode string.
RETURNS (numpy.ndarray or cupy.ndarray): A word vector. Size
@@ -436,9 +468,9 @@ cdef class Vocab:
setters = ["strings", "vectors"]
if "strings" not in exclude:
self.strings.to_disk(path / "strings.json")
- if "vectors" not in "exclude":
+ if "vectors" not in exclude:
self.vectors.to_disk(path, exclude=["strings"])
- if "lookups" not in "exclude":
+ if "lookups" not in exclude:
self.lookups.to_disk(path)
def from_disk(self, path, *, exclude=tuple()):
diff --git a/website/.dockerignore b/website/.dockerignore
new file mode 100644
index 000000000..e4a88552e
--- /dev/null
+++ b/website/.dockerignore
@@ -0,0 +1,9 @@
+.cache/
+.next/
+public/
+node_modules
+.npm
+logs
+*.log
+npm-debug.log*
+quickstart-training-generator.js
diff --git a/website/.eslintrc.json b/website/.eslintrc.json
new file mode 100644
index 000000000..1c2aa65d7
--- /dev/null
+++ b/website/.eslintrc.json
@@ -0,0 +1,3 @@
+{
+ "extends": "next/core-web-vitals"
+}
diff --git a/website/.gitignore b/website/.gitignore
new file mode 100644
index 000000000..599c0953a
--- /dev/null
+++ b/website/.gitignore
@@ -0,0 +1,46 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+quickstart-training-generator.js
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+!.vscode/extensions.json
+!public
+
+public/robots.txt
+public/sitemap*
+public/sw.js*
+public/workbox*
diff --git a/website/.nvmrc b/website/.nvmrc
new file mode 100644
index 000000000..3c032078a
--- /dev/null
+++ b/website/.nvmrc
@@ -0,0 +1 @@
+18
diff --git a/website/.prettierignore b/website/.prettierignore
new file mode 100644
index 000000000..d0d878e40
--- /dev/null
+++ b/website/.prettierignore
@@ -0,0 +1 @@
+.next
\ No newline at end of file
diff --git a/website/.prettierrc b/website/.prettierrc
index 7555c734a..03904b1c4 100644
--- a/website/.prettierrc
+++ b/website/.prettierrc
@@ -20,12 +20,11 @@
}
},
{
- "files": "*.md",
+ "files": ["package.json", "package-lock.json"],
"options": {
"tabWidth": 2,
"printWidth": 80,
- "proseWrap": "always",
- "htmlWhitespaceSensitivity": "strict"
+ "proseWrap": "always"
}
},
{
diff --git a/website/.vscode/extensions.json b/website/.vscode/extensions.json
new file mode 100644
index 000000000..4b533827a
--- /dev/null
+++ b/website/.vscode/extensions.json
@@ -0,0 +1,8 @@
+{
+ "recommendations": [
+ "dbaeumer.vscode-eslint",
+ "unifiedjs.vscode-mdx",
+ "esbenp.prettier-vscode",
+ "syler.sass-indented"
+ ]
+}
diff --git a/website/Dockerfile b/website/Dockerfile
index f71733e55..9b2f6cac4 100644
--- a/website/Dockerfile
+++ b/website/Dockerfile
@@ -1,16 +1,14 @@
-FROM node:11.15.0
+FROM node:18
-WORKDIR /spacy-io
-
-RUN npm install -g gatsby-cli@2.7.4
-
-COPY package.json .
-COPY package-lock.json .
-
-RUN npm install
+USER node
# This is so the installed node_modules will be up one directory
# from where a user mounts files, so that they don't accidentally mount
# their own node_modules from a different build
# https://nodejs.org/api/modules.html#modules_loading_from_node_modules_folders
-WORKDIR /spacy-io/website/
+WORKDIR /home/node
+COPY --chown=node package.json .
+COPY --chown=node package-lock.json .
+RUN npm install
+
+WORKDIR /home/node/website/
diff --git a/website/README.md b/website/README.md
index db050cf03..a434efe9a 100644
--- a/website/README.md
+++ b/website/README.md
@@ -1,543 +1,22 @@
-
-
# spacy.io website and docs

-_This page contains the documentation and styleguide for the spaCy website. Its
-rendered version is available at https://spacy.io/styleguide._
+The styleguide for the spaCy website is available at
+[spacy.io/styleguide](https://spacy.io/styleguide).
----
-
-
-
-The [spacy.io](https://spacy.io) website is implemented using
-[Gatsby](https://www.gatsbyjs.org) with
-[Remark](https://github.com/remarkjs/remark) and [MDX](https://mdxjs.com/). This
-allows authoring content in **straightforward Markdown** without the usual
-limitations. Standard elements can be overwritten with powerful
-[React](http://reactjs.org/) components and wherever Markdown syntax isn't
-enough, JSX components can be used.
-
-> #### Contributing to the site
->
-> The docs can always use another example or more detail, and they should always
-> be up to date and not misleading. We always appreciate a
-> [pull request](https://github.com/explosion/spaCy/pulls). To quickly find the
-> correct file to edit, simply click on the "Suggest edits" button at the bottom
-> of a page.
->
-> For more details on editing the site locally, see the installation
-> instructions and markdown reference below.
-
-## Logo {#logo source="website/src/images/logo.svg"}
-
-import { Logos } from 'widgets/styleguide'
-
-If you would like to use the spaCy logo on your site, please get in touch and
-ask us first. However, if you want to show support and tell others that your
-project is using spaCy, you can grab one of our
-[spaCy badges](/usage/spacy-101#faq-project-with-spacy).
-
-
-
-## Colors {#colors}
-
-import { Colors, Patterns } from 'widgets/styleguide'
-
-
-
-### Patterns
-
-
-
-## Typography {#typography}
-
-import { H1, H2, H3, H4, H5, Label, InlineList, Comment } from
-'components/typography'
-
-> #### Markdown
->
-> ```markdown_
-> ## Headline 2
-> ## Headline 2 {#some_id}
-> ## Headline 2 {#some_id tag="method"}
-> ```
->
-> #### JSX
->
-> ```jsx
->
Headline 2
->
Headline 2
->
Headline 2
-> ```
-
-Headlines are set in
-[HK Grotesk](http://cargocollective.com/hanken/HK-Grotesk-Open-Source-Font) by
-Hanken Design. All other body text and code uses the best-matching default
-system font to provide a "native" reading experience. All code uses the
-[JetBrains Mono](https://www.jetbrains.com/lp/mono/) typeface by JetBrains.
-
-
-
-Level 2 headings are automatically wrapped in `` elements at compile
-time, using a custom
-[Markdown transformer](https://github.com/explosion/spaCy/tree/master/website/plugins/remark-wrap-section.js).
-This makes it easier to highlight the section that's currently in the viewpoint
-in the sidebar menu.
-
-
-
-
-
Headline 1
-
Headline 2
-
Headline 3
-
Headline 4
-
Headline 5
-
-
-
----
-
-The following optional attributes can be set on the headline to modify it. For
-example, to add a tag for the documented type or mark features that have been
-introduced in a specific version or require statistical models to be loaded.
-Tags are also available as standalone `` components.
-
-| Argument | Example | Result |
-| -------- | -------------------------- | ----------------------------------------- |
-| `tag` | `{tag="method"}` | method |
-| `new` | `{new="3"}` | 3 |
-| `model` | `{model="tagger, parser"}` | tagger, parser |
-| `hidden` | `{hidden="true"}` | |
-
-## Elements {#elements}
-
-### Links {#links}
-
-> #### Markdown
->
-> ```markdown
-> [I am a link](https://spacy.io)
-> ```
->
-> #### JSX
->
-> ```jsx
-> I am a link
-> ```
-
-Special link styles are used depending on the link URL.
-
-- [I am a regular external link](https://explosion.ai)
-- [I am a link to the documentation](/api/doc)
-- [I am a link to an architecture](/api/architectures#HashEmbedCNN)
-- [I am a link to a model](/models/en#en_core_web_sm)
-- [I am a link to GitHub](https://github.com/explosion/spaCy)
-
-### Abbreviations {#abbr}
-
-import { Abbr } from 'components/typography'
-
-> #### JSX
->
-> ```jsx
-> Abbreviation
-> ```
-
-Some text with an abbreviation. On small
-screens, I collapse and the explanation text is displayed next to the
-abbreviation.
-
-### Tags {#tags}
-
-import Tag from 'components/tag'
-
-> ```jsx
-> method
-> 2.1
-> tagger, parser
-> ```
-
-Tags can be used together with headlines, or next to properties across the
-documentation, and combined with tooltips to provide additional information. An
-optional `variant` argument can be used for special tags. `variant="new"` makes
-the tag take a version number to mark new features. Using the component,
-visibility of this tag can later be toggled once the feature isn't considered
-new anymore. Setting `variant="model"` takes a description of model capabilities
-and can be used to mark features that require a respective model to be
-installed.
-
-
-
-method2tagger,
-parser
-
-
-
-### Buttons {#buttons}
-
-import Button from 'components/button'
-
-> ```jsx
->
->
-> ```
-
-Link buttons come in two variants, `primary` and `secondary` and two sizes, with
-an optional `large` size modifier. Since they're mostly used as enhanced links,
-the buttons are implemented as styled links instead of native button elements.
-
-
-
-
-
-
-
-
-
-## Components
-
-### Table {#table}
-
-> #### Markdown
->
-> ```markdown_
-> | Header 1 | Header 2 |
-> | -------- | -------- |
-> | Column 1 | Column 2 |
-> ```
->
-> #### JSX
->
-> ```markup
->
->
Header 1
Header 2
->
Column 1
Column 2
->
-> ```
-
-Tables are used to present data and API documentation. Certain keywords can be
-used to mark a footer row with a distinct style, for example to visualize the
-return values of a documented function.
-
-| Header 1 | Header 2 | Header 3 | Header 4 |
-| ----------- | -------- | :------: | -------: |
-| Column 1 | Column 2 | Column 3 | Column 4 |
-| Column 1 | Column 2 | Column 3 | Column 4 |
-| Column 1 | Column 2 | Column 3 | Column 4 |
-| Column 1 | Column 2 | Column 3 | Column 4 |
-| **RETURNS** | Column 2 | Column 3 | Column 4 |
-
-Tables also support optional "divider" rows that are typically used to denote
-keyword-only arguments in API documentation. To turn a row into a dividing
-headline, it should only include content in its first cell, and its value should
-be italicized:
-
-> #### Markdown
->
-> ```markdown_
-> | Header 1 | Header 2 | Header 3 |
-> | -------- | -------- | -------- |
-> | Column 1 | Column 2 | Column 3 |
-> | _Hello_ | | |
-> | Column 1 | Column 2 | Column 3 |
-> ```
-
-| Header 1 | Header 2 | Header 3 |
-| -------- | -------- | -------- |
-| Column 1 | Column 2 | Column 3 |
-| _Hello_ | | |
-| Column 1 | Column 2 | Column 3 |
-
-### Type Annotations {#type-annotations}
-
-> #### Markdown
->
-> ```markdown_
-> ~~Model[List[Doc], Floats2d]~~
-> ```
->
-> #### JSX
->
-> ```markup
-> Model[List[Doc], Floats2d]
-> ```
-
-Type annotations are special inline code blocks are used to describe Python
-types in the [type hints](https://docs.python.org/3/library/typing.html) format.
-The special component will split the type, apply syntax highlighting and link
-all types that specify links in `meta/type-annotations.json`. Types can link to
-internal or external documentation pages. To make it easy to represent the type
-annotations in Markdown, the rendering "hijacks" the `~~` tags that would
-typically be converted to a `` element – but in this case, text surrounded
-by `~~` becomes a type annotation.
-
-- ~~Dict[str, List[Union[Doc, Span]]]~~
-- ~~Model[List[Doc], List[numpy.ndarray]]~~
-
-Type annotations support a special visual style in tables and will render as a
-separate row, under the cell text. This allows the API docs to display complex
-types without taking up too much space in the cell. The type annotation should
-always be the **last element** in the row.
-
-> #### Markdown
->
-> ```markdown_
-> | Header 1 | Header 2 |
-> | -------- | ----------------------- |
-> | Column 1 | Column 2 ~~List[Doc]~~ |
-> ```
-
-| Name | Description |
-| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `vocab` | The shared vocabulary. ~~Vocab~~ |
-| `model` | The Thinc [`Model`](https://thinc.ai/docs/api-model) wrapping the transformer. ~~Model[List[Doc], FullTransformerBatch]~~ |
-| `set_extra_annotations` | Function that takes a batch of `Doc` objects and transformer outputs and can set additional annotations on the `Doc`. ~~Callable[[List[Doc], FullTransformerBatch], None]~~ |
-
-### List {#list}
-
-> #### Markdown
->
-> ```markdown_
-> 1. One
-> 2. Two
-> ```
->
-> #### JSX
->
-> ```markup
->
->
One
->
Two
->
-> ```
-
-Lists are available as bulleted and numbered. Markdown lists are transformed
-automatically.
-
-- I am a bulleted list
-- I have nice bullets
-- Lorem ipsum dolor
-- consectetur adipiscing elit
-
-1. I am an ordered list
-2. I have nice numbers
-3. Lorem ipsum dolor
-4. consectetur adipiscing elit
-
-### Aside {#aside}
-
-> #### Markdown
->
-> ```markdown_
-> > #### Aside title
-> > This is aside text.
-> ```
->
-> #### JSX
->
-> ```jsx
->
-> ```
-
-Asides can be used to display additional notes and content in the right-hand
-column. Asides can contain text, code and other elements if needed. Visually,
-asides are moved to the side on the X-axis, and displayed at the same level they
-were inserted. On small screens, they collapse and are rendered in their
-original position, in between the text.
-
-To make them easier to use in Markdown, paragraphs formatted as blockquotes will
-turn into asides by default. Level 4 headlines (with a leading `####`) will
-become aside titles.
-
-### Code Block {#code-block}
-
-> #### Markdown
->
-> ````markdown_
-> ```python
-> ### This is a title
-> import spacy
-> ```
-> ````
->
-> #### JSX
->
-> ```jsx
->
-> import spacy
->
-> ```
-
-Code blocks use the [Prism](http://prismjs.com/) syntax highlighter with a
-custom theme. The language can be set individually on each block, and defaults
-to raw text with no highlighting. An optional label can be added as the first
-line with the prefix `####` (Python-like) and `///` (JavaScript-like). the
-indented block as plain text and preserve whitespace.
-
-```python
-### Using spaCy
-import spacy
-nlp = spacy.load("en_core_web_sm")
-doc = nlp("This is a sentence.")
-for token in doc:
- print(token.text, token.pos_)
-```
-
-Code blocks and also specify an optional range of line numbers to highlight by
-adding `{highlight="..."}` to the headline. Acceptable ranges are spans like
-`5-7`, but also `5-7,10` or `5-7,10,13-14`.
-
-> #### Markdown
->
-> ````markdown_
-> ```python
-> ### This is a title {highlight="1-2"}
-> import spacy
-> nlp = spacy.load("en_core_web_sm")
-> ```
-> ````
-
-```python
-### Using the matcher {highlight="5-7"}
-import spacy
-from spacy.matcher import Matcher
-
-nlp = spacy.load('en_core_web_sm')
-matcher = Matcher(nlp.vocab)
-pattern = [{"LOWER": "hello"}, {"IS_PUNCT": True}, {"LOWER": "world"}]
-matcher.add("HelloWorld", None, pattern)
-doc = nlp("Hello, world! Hello world!")
-matches = matcher(doc)
-```
-
-Adding `{executable="true"}` to the title turns the code into an executable
-block, powered by [Binder](https://mybinder.org) and
-[Juniper](https://github.com/ines/juniper). If JavaScript is disabled, the
-interactive widget defaults to a regular code block.
-
-> #### Markdown
->
-> ````markdown_
-> ```python
-> ### {executable="true"}
-> import spacy
-> nlp = spacy.load("en_core_web_sm")
-> ```
-> ````
-
-```python
-### {executable="true"}
-import spacy
-nlp = spacy.load("en_core_web_sm")
-doc = nlp("This is a sentence.")
-for token in doc:
- print(token.text, token.pos_)
-```
-
-If a code block only contains a URL to a GitHub file, the raw file contents are
-embedded automatically and syntax highlighting is applied. The link to the
-original file is shown at the top of the widget.
-
-> #### Markdown
->
-> ````markdown_
-> ```python
-> https://github.com/...
-> ```
-> ````
->
-> #### JSX
->
-> ```jsx
->
-> ```
-
-```python
-https://github.com/explosion/spaCy/tree/master/spacy/language.py
-```
-
-### Infobox {#infobox}
-
-import Infobox from 'components/infobox'
-
-> #### JSX
->
-> ```jsx
-> Regular infobox
-> This is a warning.
-> This is dangerous.
-> ```
-
-Infoboxes can be used to add notes, updates, warnings or additional information
-to a page or section. Semantically, they're implemented and interpreted as an
-`aside` element. Infoboxes can take an optional `title` argument, as well as an
-optional `variant` (either `"warning"` or `"danger"`).
-
-
-
-If needed, an infobox can contain regular text, `inline code`, lists and other
-blocks.
-
-
-
-
-
-If needed, an infobox can contain regular text, `inline code`, lists and other
-blocks.
-
-
-
-
-
-If needed, an infobox can contain regular text, `inline code`, lists and other
-blocks.
-
-
-
-### Accordion {#accordion}
-
-import Accordion from 'components/accordion'
-
-> #### JSX
->
-> ```jsx
->
-> Accordion content goes here.
->
-> ```
-
-Accordions are collapsible sections that are mostly used for lengthy tables,
-like the tag and label annotation schemes for different languages. They all need
-to be presented – but chances are the user doesn't actually care about _all_ of
-them, especially not at the same time. So it's fairly reasonable to hide them
-begin a click. This particular implementation was inspired by the amazing
-[Inclusive Components blog](https://inclusive-components.design/collapsible-sections/).
-
-
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque enim ante,
-pretium a orci eget, varius dignissim augue. Nam eu dictum mauris, id tincidunt
-nisi. Integer commodo pellentesque tincidunt. Nam at turpis finibus tortor
-gravida sodales tincidunt sit amet est. Nullam euismod arcu in tortor auctor,
-sit amet dignissim justo congue.
-
-
-
-## Setup and installation {#setup}
-
-Before running the setup, make sure your versions of
-[Node](https://nodejs.org/en/) and [npm](https://www.npmjs.com/) are up to date.
-Node v10.15 or later is required.
+## Setup and installation
```bash
# Clone the repository
git clone https://github.com/explosion/spaCy
cd spaCy/website
-# Install Gatsby's command-line tool
-npm install --global gatsby-cli
+# Switch to the correct Node version
+#
+# If you don't have NVM and don't want to use it, you can manually switch to the Node version
+# stated in /.nvmrc and skip this step
+nvm use
# Install the dependencies
npm install
@@ -554,101 +33,50 @@ extensions for your code editor. The
[`.prettierrc`](https://github.com/explosion/spaCy/tree/master/website/.prettierrc)
file in the root defines the settings used in this codebase.
-## Building & developing the site with Docker {#docker}
-Sometimes it's hard to get a local environment working due to rapid updates to node dependencies,
-so it may be easier to use docker for building the docs.
+## Building & developing the site with Docker
-If you'd like to do this,
-**be sure you do *not* include your local `node_modules` folder**,
-since there are some dependencies that need to be built for the image system.
-Rename it before using.
+While it shouldn't be necessary and is not recommended you can run this site in a Docker container.
-```bash
-docker run -it \
- -v $(pwd):/spacy-io/website \
- -p 8000:8000 \
- ghcr.io/explosion/spacy-io \
- gatsby develop -H 0.0.0.0
-```
+If you'd like to do this, **be sure you do _not_ include your local
+`node_modules` folder**, since there are some dependencies that need to be built
+for the image system. Rename it before using.
-This will allow you to access the built website at http://0.0.0.0:8000/
-in your browser, and still edit code in your editor while having the site
-reflect those changes.
-
-**Note**: If you're working on a Mac with an M1 processor,
-you might see segfault errors from `qemu` if you use the default image.
-To fix this use the `arm64` tagged image in the `docker run` command
-(ghcr.io/explosion/spacy-io:arm64).
-
-### Building the Docker image {#docker-build}
-
-If you'd like to build the image locally, you can do so like this:
+First build the Docker image. This only needs to be done on the first run
+or when changes are made to `Dockerfile` or the website dependencies:
```bash
docker build -t spacy-io .
```
-This will take some time, so if you want to use the prebuilt image you'll save a bit of time.
+You can then build and run the website with:
-## Markdown reference {#markdown}
-
-All page content and page meta lives in the `.md` files in the `/docs`
-directory. The frontmatter block at the top of each file defines the page title
-and other settings like the sidebar menu.
-
-````markdown
----
-title: Page title
----
-
-## Headline starting a section {#some_id}
-
-This is a regular paragraph with a [link](https://spacy.io) and **bold text**.
-
-> #### This is an aside title
->
-> This is aside text.
-
-### Subheadline
-
-| Header 1 | Header 2 |
-| -------- | -------- |
-| Column 1 | Column 2 |
-
-```python
-### Code block title {highlight="2-3"}
-import spacy
-nlp = spacy.load("en_core_web_sm")
-doc = nlp("Hello world")
+```bash
+docker run -it \
+ --rm \
+ -v $(pwd):/home/node/website \
+ -p 3000:3000 \
+ spacy-io \
+ npm run dev -- -H 0.0.0.0
```
-
+This will allow you to access the built website at http://0.0.0.0:3000/ in your
+browser, and still edit code in your editor while having the site reflect those
+changes.
-This is content in the infobox.
-
-
-````
-
-In addition to the native markdown elements, you can use the components
-[``][infobox], [``][accordion], [``][abbr] and
-[``][tag] via their JSX syntax.
-
-[infobox]: https://spacy.io/styleguide#infobox
-[accordion]: https://spacy.io/styleguide#accordion
-[abbr]: https://spacy.io/styleguide#abbr
-[tag]: https://spacy.io/styleguide#tag
-
-## Project structure {#structure}
+## Project structure
```yaml
-### Directory structure
├── docs # the actual markdown content
├── meta # JSON-formatted site metadata
+| ├── dynamicMeta.js # At build time generated meta data
| ├── languages.json # supported languages and statistical models
| ├── sidebars.json # sidebar navigations for different sections
| ├── site.json # general site metadata
+| ├── type-annotations.json # Type annotations
| └── universe.json # data for the spaCy universe section
-├── public # compiled site
+├── pages # Next router pages
+├── public # static images and other assets
+├── setup # Jinja setup
├── src # source
| ├── components # React components
| ├── fonts # webfonts
@@ -661,54 +89,12 @@ In addition to the native markdown elements, you can use the components
| | ├── models.js # layout template for model pages
| | └── universe.js # layout templates for universe
| └── widgets # non-reusable components with content, e.g. changelog
-├── gatsby-browser.js # browser-specific hooks for Gatsby
-├── gatsby-config.js # Gatsby configuration
-├── gatsby-node.js # Node-specific hooks for Gatsby
-└── package.json # package settings and dependencies
+├── .eslintrc.json # ESLint config file
+├── .nvmrc # NVM config file
+| # (to support "nvm use" to switch to correct Node version)
+|
+├── .prettierrc # Prettier config file
+├── next.config.mjs # Next config file
+├── package.json # package settings and dependencies
+└── tsconfig.json # TypeScript config file
```
-
-## Editorial {#editorial}
-
-- "spaCy" should always be spelled with a lowercase "s" and a capital "C",
- unless it specifically refers to the Python package or Python import `spacy`
- (in which case it should be formatted as code).
- - ✅ spaCy is a library for advanced NLP in Python.
- - ❌ Spacy is a library for advanced NLP in Python.
- - ✅ First, you need to install the `spacy` package from pip.
-- Mentions of code, like function names, classes, variable names etc. in inline
- text should be formatted as `code`.
- - ✅ "Calling the `nlp` object on a text returns a `Doc`."
-- Objects that have pages in the [API docs](/api) should be linked – for
- example, [`Doc`](/api/doc) or [`Language.to_disk`](/api/language#to_disk). The
- mentions should still be formatted as code within the link. Links pointing to
- the API docs will automatically receive a little icon. However, if a paragraph
- includes many references to the API, the links can easily get messy. In that
- case, we typically only link the first mention of an object and not any
- subsequent ones.
- - ✅ The [`Span`](/api/span) and [`Token`](/api/token) objects are views of a
- [`Doc`](/api/doc). [`Span.as_doc`](/api/span#as_doc) creates a `Doc` object
- from a `Span`.
- - ❌ The [`Span`](/api/span) and [`Token`](/api/token) objects are views of a
- [`Doc`](/api/doc). [`Span.as_doc`](/api/span#as_doc) creates a
- [`Doc`](/api/doc) object from a [`Span`](/api/span).
-
-* Other things we format as code are: references to trained pipeline packages
- like `en_core_web_sm` or file names like `code.py` or `meta.json`.
-
- - ✅ After training, the `config.cfg` is saved to disk.
-
-* [Type annotations](#type-annotations) are a special type of code formatting,
- expressed by wrapping the text in `~~` instead of backticks. The result looks
- like this: ~~List[Doc]~~. All references to known types will be linked
- automatically.
-
- - ✅ The model has the input type ~~List[Doc]~~ and it outputs a
- ~~List[Array2d]~~.
-
-* We try to keep links meaningful but short.
- - ✅ For details, see the usage guide on
- [training with custom code](/usage/training#custom-code).
- - ❌ For details, see
- [the usage guide on training with custom code](/usage/training#custom-code).
- - ❌ For details, see the usage guide on training with custom code
- [here](/usage/training#custom-code).
diff --git a/website/UNIVERSE.md b/website/UNIVERSE.md
index 770bbde13..ac4e2e684 100644
--- a/website/UNIVERSE.md
+++ b/website/UNIVERSE.md
@@ -2,42 +2,52 @@
# spaCy Universe
-The [spaCy Universe](https://spacy.io/universe) collects the many great resources developed with or for spaCy. It
-includes standalone packages, plugins, extensions, educational materials,
-operational utilities and bindings for other languages.
+The [spaCy Universe](https://spacy.io/universe) collects the many great
+resources developed with or for spaCy. It includes standalone packages, plugins,
+extensions, educational materials, operational utilities and bindings for other
+languages.
If you have a project that you want the spaCy community to make use of, you can
suggest it by submitting a pull request to this repository. The Universe
database is open-source and collected in a simple JSON file.
Looking for inspiration for your own spaCy plugin or extension? Check out the
-[`project ideas`](https://github.com/explosion/spaCy/discussions?discussions_q=category%3A%22New+Features+%26+Project+Ideas%22)
+[`project ideas`](https://github.com/explosion/spaCy/discussions?discussions_q=category%3A%22New+Features+%26+Project+Ideas%22)
discussion forum.
## Checklist
### Projects
-✅ Libraries and packages should be **open-source** (with a user-friendly license) and at least somewhat **documented** (e.g. a simple `README` with usage instructions).
+✅ Libraries and packages should be **open-source** (with a user-friendly
+license) and at least somewhat **documented** (e.g. a simple `README` with usage
+instructions).
-✅ We're happy to include work in progress and prereleases, but we'd like to keep the emphasis on projects that should be useful to the community **right away**.
+✅ We're happy to include work in progress and prereleases, but we'd like to
+keep the emphasis on projects that should be useful to the community **right
+away**.
✅ Demos and visualizers should be available via a **public URL**.
### Educational Materials
-✅ Books should be **available for purchase or download** (not just pre-order). Ebooks and self-published books are fine, too, if they include enough substantial content.
+✅ Books should be **available for purchase or download** (not just pre-order).
+Ebooks and self-published books are fine, too, if they include enough
+substantial content.
-✅ The `"url"` of book entries should either point to the publisher's website or a reseller of your choice (ideally one that ships worldwide or as close as possible).
+✅ The `"url"` of book entries should either point to the publisher's website or
+a reseller of your choice (ideally one that ships worldwide or as close as
+possible).
-✅ If an online course is only available behind a paywall, it should at least have a **free excerpt** or chapter available, so users know what to expect.
+✅ If an online course is only available behind a paywall, it should at least
+have a **free excerpt** or chapter available, so users know what to expect.
## JSON format
-To add a project, fork this repository, edit the [`universe.json`](meta/universe.json)
-and add an object of the following format to the list of `"resources"`. Before
-you submit your pull request, make sure to use a linter to verify that your
-markup is correct.
+To add a project, fork this repository, edit the
+[`universe.json`](meta/universe.json) and add an object of the following format
+to the list of `"resources"`. Before you submit your pull request, make sure to
+use a linter to verify that your markup is correct.
```json
{
@@ -69,26 +79,26 @@ markup is correct.
}
```
-| Field | Type | Description |
-| --- | --- | --- |
-| `id` | string | Unique ID of the project. |
-| `title` | string | Project title. If not set, the `id` will be used as the display title. |
-| `slogan` | string | A short description of the project. Displayed in the overview and under the title. |
-| `description` | string | A longer description of the project. Markdown is allowed, but should be limited to basic formatting like bold, italics, code or links. |
-| `github` | string | Associated GitHub repo in the format `user/repo`. Will be displayed as a link and used for release, license and star badges. |
-| `pip` | string | Package name on pip. If available, the installation command will be displayed. |
-| `cran` | string | For R packages: package name on CRAN. If available, the installation command will be displayed. |
-| `code_example` | array | Short example that shows how to use the project. Formatted as an array with one string per line. |
-| `code_language` | string | Defaults to `'python'`. Optional code language used for syntax highlighting with [Prism](http://prismjs.com/). |
-| `url` | string | Optional project link to display as button. |
-| `thumb` | string | Optional URL to project thumbnail to display in overview and project header. Recommended size is 100x100px. |
-| `image` | string | Optional URL to project image to display with description. |
-| `author` | string | Name(s) of project author(s). |
-| `author_links` | object | Usernames and links to display as icons to author info. Currently supports `twitter` and `github` usernames, as well as `website` link. |
-| `category` | list | One or more categories to assign to project. Must be one of the available options. |
-| `tags` | list | Still experimental and not used for filtering: one or more tags to assign to project. |
+| Field | Type | Description |
+| --------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `id` | string | Unique ID of the project. |
+| `title` | string | Project title. If not set, the `id` will be used as the display title. |
+| `slogan` | string | A short description of the project. Displayed in the overview and under the title. |
+| `description` | string | A longer description of the project. Markdown is allowed, but should be limited to basic formatting like bold, italics, code or links. |
+| `github` | string | Associated GitHub repo in the format `user/repo`. Will be displayed as a link and used for release, license and star badges. |
+| `pip` | string | Package name on pip. If available, the installation command will be displayed. |
+| `cran` | string | For R packages: package name on CRAN. If available, the installation command will be displayed. |
+| `code_example` | array | Short example that shows how to use the project. Formatted as an array with one string per line. |
+| `code_language` | string | Defaults to `'python'`. Optional code language used for syntax highlighting with [Prism](http://prismjs.com/). |
+| `url` | string | Optional project link to display as button. |
+| `thumb` | string | Optional URL to project thumbnail to display in overview and project header. Recommended size is 100x100px. |
+| `image` | string | Optional URL to project image to display with description. |
+| `author` | string | Name(s) of project author(s). |
+| `author_links` | object | Usernames and links to display as icons to author info. Currently supports `twitter` and `github` usernames, as well as `website` link. |
+| `category` | list | One or more categories to assign to project. Must be one of the available options. |
+| `tags` | list | Still experimental and not used for filtering: one or more tags to assign to project. |
To separate them from the projects, educational materials also specify
-`"type": "education`. Books can also set a `"cover"` field containing a URL
-to a cover image. If available, it's used in the overview and displayed on
-the individual book page.
+`"type": "education`. Books can also set a `"cover"` field containing a URL to a
+cover image. If available, it's used in the overview and displayed on the
+individual book page.
diff --git a/website/docs/api/architectures.md b/website/docs/api/architectures.mdx
similarity index 87%
rename from website/docs/api/architectures.md
rename to website/docs/api/architectures.mdx
index 07b76393f..2a1bc4380 100644
--- a/website/docs/api/architectures.md
+++ b/website/docs/api/architectures.mdx
@@ -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
@@ -25,9 +26,9 @@ part of the [training config](/usage/training#custom-functions). Also see the
usage documentation on
[layers and model architectures](/usage/layers-architectures).
-## Tok2Vec architectures {#tok2vec-arch source="spacy/ml/models/tok2vec.py"}
+## Tok2Vec architectures {id="tok2vec-arch",source="spacy/ml/models/tok2vec.py"}
-### spacy.Tok2Vec.v2 {#Tok2Vec}
+### spacy.Tok2Vec.v2 {id="Tok2Vec"}
> #### Example config
>
@@ -55,7 +56,7 @@ blog post for background.
| `encode` | Encode context into the embeddings, using an architecture such as a CNN, BiLSTM or transformer. For example, [MaxoutWindowEncoder](/api/architectures#MaxoutWindowEncoder). ~~Model[List[Floats2d], List[Floats2d]]~~ |
| **CREATES** | The model using the architecture. ~~Model[List[Doc], List[Floats2d]]~~ |
-### spacy.HashEmbedCNN.v2 {#HashEmbedCNN}
+### spacy.HashEmbedCNN.v2 {id="HashEmbedCNN"}
> #### Example Config
>
@@ -88,7 +89,7 @@ consisting of a CNN and a layer-normalized maxout activation function.
| `pretrained_vectors` | Whether to also use static vectors. ~~bool~~ |
| **CREATES** | The model using the architecture. ~~Model[List[Doc], List[Floats2d]]~~ |
-### spacy.Tok2VecListener.v1 {#Tok2VecListener}
+### spacy.Tok2VecListener.v1 {id="Tok2VecListener"}
> #### Example config
>
@@ -104,7 +105,7 @@ consisting of a CNN and a layer-normalized maxout activation function.
> factory = "tagger"
>
> [components.tagger.model]
-> @architectures = "spacy.Tagger.v1"
+> @architectures = "spacy.Tagger.v2"
>
> [components.tagger.model.tok2vec]
> @architectures = "spacy.Tok2VecListener.v1"
@@ -138,7 +139,7 @@ the `Tok2Vec` component.
| `upstream` | A string to identify the "upstream" `Tok2Vec` component to communicate with. By default, the upstream name is the wildcard string `"*"`, but you could also specify the name of the `Tok2Vec` component. You'll almost never have multiple upstream `Tok2Vec` components, so the wildcard string will almost always be fine. ~~str~~ |
| **CREATES** | The model using the architecture. ~~Model[List[Doc], List[Floats2d]]~~ |
-### spacy.MultiHashEmbed.v2 {#MultiHashEmbed}
+### spacy.MultiHashEmbed.v2 {id="MultiHashEmbed"}
> #### Example config
>
@@ -158,8 +159,8 @@ be configured with the `attrs` argument. The suggested attributes are `NORM`,
`PREFIX`, `SUFFIX` and `SHAPE`. This lets the model take into account some
subword information, without construction a fully character-based
representation. If pretrained vectors are available, they can be included in the
-representation as well, with the vectors table kept static (i.e. it's
-not updated).
+representation as well, with the vectors table kept static (i.e. it's not
+updated).
| Name | Description |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -169,7 +170,7 @@ not updated).
| `include_static_vectors` | Whether to also use static word vectors. Requires a vectors table to be loaded in the [`Doc`](/api/doc) objects' vocab. ~~bool~~ |
| **CREATES** | The model using the architecture. ~~Model[List[Doc], List[Floats2d]]~~ |
-### spacy.CharacterEmbed.v2 {#CharacterEmbed}
+### spacy.CharacterEmbed.v2 {id="CharacterEmbed"}
> #### Example config
>
@@ -206,7 +207,7 @@ network to construct a single vector to represent the information.
| `nC` | The number of UTF-8 bytes to embed per word. Recommended values are between `3` and `8`, although it may depend on the length of words in the language. ~~int~~ |
| **CREATES** | The model using the architecture. ~~Model[List[Doc], List[Floats2d]]~~ |
-### spacy.MaxoutWindowEncoder.v2 {#MaxoutWindowEncoder}
+### spacy.MaxoutWindowEncoder.v2 {id="MaxoutWindowEncoder"}
> #### Example config
>
@@ -230,7 +231,7 @@ and residual connections.
| `depth` | The number of convolutional layers. Recommended value is `4`. ~~int~~ |
| **CREATES** | The model using the architecture. ~~Model[List[Floats2d], List[Floats2d]]~~ |
-### spacy.MishWindowEncoder.v2 {#MishWindowEncoder}
+### spacy.MishWindowEncoder.v2 {id="MishWindowEncoder"}
> #### Example config
>
@@ -253,7 +254,7 @@ and residual connections.
| `depth` | The number of convolutional layers. Recommended value is `4`. ~~int~~ |
| **CREATES** | The model using the architecture. ~~Model[List[Floats2d], List[Floats2d]]~~ |
-### spacy.TorchBiLSTMEncoder.v1 {#TorchBiLSTMEncoder}
+### spacy.TorchBiLSTMEncoder.v1 {id="TorchBiLSTMEncoder"}
> #### Example config
>
@@ -275,7 +276,7 @@ Encode context using bidirectional LSTM layers. Requires
| `dropout` | Creates a Dropout layer on the outputs of each LSTM layer except the last layer. Set to 0.0 to disable this functionality. ~~float~~ |
| **CREATES** | The model using the architecture. ~~Model[List[Floats2d], List[Floats2d]]~~ |
-### spacy.StaticVectors.v2 {#StaticVectors}
+### spacy.StaticVectors.v2 {id="StaticVectors"}
> #### Example config
>
@@ -305,7 +306,7 @@ mapped to a zero vector. See the documentation on
| `key_attr` | Defaults to `"ORTH"`. ~~str~~ |
| **CREATES** | The model using the architecture. ~~Model[List[Doc], Ragged]~~ |
-### spacy.FeatureExtractor.v1 {#FeatureExtractor}
+### spacy.FeatureExtractor.v1 {id="FeatureExtractor"}
> #### Example config
>
@@ -323,7 +324,7 @@ of feature names to extract, which should refer to token attributes.
| `columns` | The token attributes to extract. ~~List[Union[int, str]]~~ |
| **CREATES** | The created feature extraction layer. ~~Model[List[Doc], List[Ints2d]]~~ |
-## Transformer architectures {#transformers source="github.com/explosion/spacy-transformers/blob/master/spacy_transformers/architectures.py"}
+## Transformer architectures {id="transformers",source="github.com/explosion/spacy-transformers/blob/master/spacy_transformers/architectures.py"}
The following architectures are provided by the package
[`spacy-transformers`](https://github.com/explosion/spacy-transformers). See the
@@ -340,7 +341,7 @@ for details and system requirements.
-### spacy-transformers.TransformerModel.v3 {#TransformerModel}
+### spacy-transformers.TransformerModel.v3 {id="TransformerModel"}
> #### Example Config
>
@@ -389,7 +390,7 @@ in other components, see
| | |
-Mixed-precision support is currently an experimental feature.
+ Mixed-precision support is currently an experimental feature.
@@ -403,7 +404,7 @@ The other arguments are shared between all versions.
-### spacy-transformers.TransformerListener.v1 {#TransformerListener}
+### spacy-transformers.TransformerListener.v1 {id="TransformerListener"}
> #### Example Config
>
@@ -433,7 +434,7 @@ a single token vector given zero or more wordpiece vectors.
| `upstream` | A string to identify the "upstream" `Transformer` component to communicate with. By default, the upstream name is the wildcard string `"*"`, but you could also specify the name of the `Transformer` component. You'll almost never have multiple upstream `Transformer` components, so the wildcard string will almost always be fine. ~~str~~ |
| **CREATES** | The model using the architecture. ~~Model[List[Doc], List[Floats2d]]~~ |
-### spacy-transformers.Tok2VecTransformer.v3 {#Tok2VecTransformer}
+### spacy-transformers.Tok2VecTransformer.v3 {id="Tok2VecTransformer"}
> #### Example Config
>
@@ -466,7 +467,7 @@ one component.
| **CREATES** | The model using the architecture. ~~Model[List[Doc], List[Floats2d]]~~ |
-Mixed-precision support is currently an experimental feature.
+ Mixed-precision support is currently an experimental feature.
@@ -480,7 +481,7 @@ The other arguments are shared between all versions.
-## Pretraining architectures {#pretrain source="spacy/ml/models/multi_task.py"}
+## Pretraining architectures {id="pretrain",source="spacy/ml/models/multi_task.py"}
The spacy `pretrain` command lets you initialize a `Tok2Vec` layer in your
pipeline with information from raw text. To this end, additional layers are
@@ -493,7 +494,7 @@ BERT.
For more information, see the section on
[pretraining](/usage/embeddings-transformers#pretraining).
-### spacy.PretrainVectors.v1 {#pretrain_vectors}
+### spacy.PretrainVectors.v1 {id="pretrain_vectors"}
> #### Example config
>
@@ -524,7 +525,7 @@ vectors.
| `loss` | The loss function can be either "cosine" or "L2". We typically recommend to use "cosine". ~~~str~~ |
| **CREATES** | A callable function that can create the Model, given the `vocab` of the pipeline and the `tok2vec` layer to pretrain. ~~Callable[[Vocab, Model], Model]~~ |
-### spacy.PretrainCharacters.v1 {#pretrain_chars}
+### spacy.PretrainCharacters.v1 {id="pretrain_chars"}
> #### Example config
>
@@ -550,9 +551,9 @@ for a Tok2Vec layer.
| `n_characters` | The window of characters - e.g. if `n_characters = 2`, the model will try to predict the first two and last two characters of the word. ~~int~~ |
| **CREATES** | A callable function that can create the Model, given the `vocab` of the pipeline and the `tok2vec` layer to pretrain. ~~Callable[[Vocab, Model], Model]~~ |
-## Parser & NER architectures {#parser}
+## Parser & NER architectures {id="parser"}
-### spacy.TransitionBasedParser.v2 {#TransitionBasedParser source="spacy/ml/models/parser.py"}
+### spacy.TransitionBasedParser.v2 {id="TransitionBasedParser",source="spacy/ml/models/parser.py"}
> #### Example Config
>
@@ -587,8 +588,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 simply 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.
@@ -611,32 +612,43 @@ same signature, but the `use_upper` argument was `True` by default.
-## Tagging architectures {#tagger source="spacy/ml/models/tagger.py"}
+## Tagging architectures {id="tagger",source="spacy/ml/models/tagger.py"}
-### spacy.Tagger.v1 {#Tagger}
+### spacy.Tagger.v2 {id="Tagger"}
> #### Example Config
>
> ```ini
> [model]
-> @architectures = "spacy.Tagger.v1"
+> @architectures = "spacy.Tagger.v2"
> nO = null
+> normalize = false
>
> [model.tok2vec]
> # ...
> ```
Build a tagger model, using a provided token-to-vector component. The tagger
-model simply 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 |
| ----------- | ------------------------------------------------------------------------------------------ |
| `tok2vec` | Subnetwork to map tokens into vector representations. ~~Model[List[Doc], List[Floats2d]]~~ |
| `nO` | The number of tags to output. Inferred from the data if `None`. ~~Optional[int]~~ |
+| `normalize` | Normalize probabilities during inference. Defaults to `False`. ~~bool~~ |
| **CREATES** | The model using the architecture. ~~Model[List[Doc], List[Floats2d]]~~ |
-## Text classification architectures {#textcat source="spacy/ml/models/textcat.py"}
+
+
+- The `normalize` argument was added in `spacy.Tagger.v2`. `spacy.Tagger.v1`
+ always normalizes probabilities during inference.
+
+The other arguments are shared between all versions.
+
+
+
+## Text classification architectures {id="textcat",source="spacy/ml/models/textcat.py"}
A text classification architecture needs to take a [`Doc`](/api/doc) as input,
and produce a score for each potential label class. Textcat challenges can be
@@ -660,7 +672,7 @@ single-label use-cases where `exclusive_classes = true`, while the
-### spacy.TextCatEnsemble.v2 {#TextCatEnsemble}
+### spacy.TextCatEnsemble.v2 {id="TextCatEnsemble"}
> #### Example Config
>
@@ -725,7 +737,7 @@ but used an internal `tok2vec` instead of taking it as argument:
-### spacy.TextCatCNN.v2 {#TextCatCNN}
+### spacy.TextCatCNN.v2 {id="TextCatCNN"}
> #### Example Config
>
@@ -765,7 +777,7 @@ after training.
-### spacy.TextCatBOW.v2 {#TextCatBOW}
+### spacy.TextCatBOW.v2 {id="TextCatBOW"}
> #### Example Config
>
@@ -797,9 +809,9 @@ after training.
-## Span classification architectures {#spancat source="spacy/ml/models/spancat.py"}
+## Span classification architectures {id="spancat",source="spacy/ml/models/spancat.py"}
-### spacy.SpanCategorizer.v1 {#SpanCategorizer}
+### spacy.SpanCategorizer.v1 {id="SpanCategorizer"}
> #### Example Config
>
@@ -836,7 +848,7 @@ single vector, and a scorer model to map the vectors to probabilities.
| `scorer` | The scorer model. ~~Model[Floats2d, Floats2d]~~ |
| **CREATES** | The model using the architecture. ~~Model[Tuple[List[Doc], Ragged], Floats2d]~~ |
-### spacy.mean_max_reducer.v1 {#mean_max_reducer}
+### spacy.mean_max_reducer.v1 {id="mean_max_reducer"}
Reduce sequences by concatenating their mean and max pooled vectors, and then
combine the concatenated vectors with a hidden layer.
@@ -845,7 +857,7 @@ combine the concatenated vectors with a hidden layer.
| ------------- | ------------------------------------- |
| `hidden_size` | The size of the hidden layer. ~~int~~ |
-## Entity linking architectures {#entitylinker source="spacy/ml/models/entity_linker.py"}
+## Entity linking architectures {id="entitylinker",source="spacy/ml/models/entity_linker.py"}
An [`EntityLinker`](/api/entitylinker) component disambiguates textual mentions
(tagged as named entities) to unique identifiers, grounding the named entities
@@ -858,13 +870,13 @@ into the "real world". This requires 3 main components:
- A machine learning [`Model`](https://thinc.ai/docs/api-model) that picks the
most plausible ID from the set of candidates.
-### spacy.EntityLinker.v1 {#EntityLinker}
+### spacy.EntityLinker.v2 {id="EntityLinker"}
> #### Example Config
>
> ```ini
> [model]
-> @architectures = "spacy.EntityLinker.v1"
+> @architectures = "spacy.EntityLinker.v2"
> nO = null
>
> [model.tok2vec]
@@ -887,7 +899,7 @@ The `EntityLinker` model architecture is a Thinc `Model` with a
| `nO` | Output dimension, determined by the length of the vectors encoding each entity in the KB. If the `nO` dimension is not set, the entity linking component will set it when `initialize` is called. ~~Optional[int]~~ |
| **CREATES** | The model using the architecture. ~~Model[List[Doc], Floats2d]~~ |
-### spacy.EmptyKB.v1 {#EmptyKB}
+### spacy.EmptyKB.v1 {id="EmptyKB"}
A function that creates an empty `KnowledgeBase` from a [`Vocab`](/api/vocab)
instance. This is the default when a new entity linker component is created.
@@ -896,7 +908,7 @@ instance. This is the default when a new entity linker component is created.
| ---------------------- | ----------------------------------------------------------------------------------- |
| `entity_vector_length` | The length of the vectors encoding each entity in the KB. Defaults to `64`. ~~int~~ |
-### spacy.KBFromFile.v1 {#KBFromFile}
+### spacy.KBFromFile.v1 {id="KBFromFile"}
A function that reads an existing `KnowledgeBase` from file.
@@ -904,10 +916,89 @@ A function that reads an existing `KnowledgeBase` from file.
| --------- | -------------------------------------------------------- |
| `kb_path` | The location of the KB that was stored to file. ~~Path~~ |
-### spacy.CandidateGenerator.v1 {#CandidateGenerator}
+### spacy.CandidateGenerator.v1 {id="CandidateGenerator"}
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` simply 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 {id="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
+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-experimental.Coref.v1 {id="Coref",tag="experimental"}
+
+> #### Example Config
+>
+> ```ini
+>
+> [model]
+> @architectures = "spacy-experimental.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-experimental.SpanResolver.v1 {id="SpanResolver",tag="experimental"}
+
+> #### Example Config
+>
+> ```ini
+>
+> [model]
+> @architectures = "spacy-experimental.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`. 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/attributeruler.md b/website/docs/api/attributeruler.mdx
similarity index 94%
rename from website/docs/api/attributeruler.md
rename to website/docs/api/attributeruler.mdx
index 965bffbcc..c18319187 100644
--- a/website/docs/api/attributeruler.md
+++ b/website/docs/api/attributeruler.mdx
@@ -2,7 +2,7 @@
title: AttributeRuler
tag: class
source: spacy/pipeline/attributeruler.py
-new: 3
+version: 3
teaser: 'Pipeline component for rule-based token attribute assignment'
api_string_name: attribute_ruler
api_trainable: false
@@ -15,7 +15,7 @@ between attributes such as mapping fine-grained POS tags to coarse-grained POS
tags. See the [usage guide](/usage/linguistic-features/#mappings-exceptions) for
examples.
-## Config and implementation {#config}
+## Config and implementation {id="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
@@ -37,7 +37,7 @@ how the component should be configured. You can override its settings via the
%%GITHUB_SPACY/spacy/pipeline/attributeruler.py
```
-## AttributeRuler.\_\_init\_\_ {#init tag="method"}
+## AttributeRuler.\_\_init\_\_ {id="init",tag="method"}
Initialize the attribute ruler.
@@ -56,7 +56,7 @@ Initialize the attribute ruler.
| `validate` | Whether patterns should be validated (passed to the [`Matcher`](/api/matcher#init)). Defaults to `False`. ~~bool~~ |
| `scorer` | The scoring method. Defaults to [`Scorer.score_token_attr`](/api/scorer#score_token_attr) for the attributes `"tag`", `"pos"`, `"morph"` and `"lemma"` and [`Scorer.score_token_attr_per_feat`](/api/scorer#score_token_attr_per_feat) for the attribute `"morph"`. ~~Optional[Callable]~~ |
-## AttributeRuler.\_\_call\_\_ {#call tag="method"}
+## AttributeRuler.\_\_call\_\_ {id="call",tag="method"}
Apply the attribute ruler to a `Doc`, setting token attributes for tokens
matched by the provided patterns.
@@ -66,7 +66,7 @@ matched by the provided patterns.
| `doc` | The document to process. ~~Doc~~ |
| **RETURNS** | The processed document. ~~Doc~~ |
-## AttributeRuler.add {#add tag="method"}
+## AttributeRuler.add {id="add",tag="method"}
Add patterns to the attribute ruler. The patterns are a list of `Matcher`
patterns and the attributes are a dict of attributes to set on the matched
@@ -89,7 +89,7 @@ may be negative to index from the end of the span.
| `attrs` | The attributes to assign to the target token in the matched span. ~~Dict[str, Any]~~ |
| `index` | The index of the token in the matched span to modify. May be negative to index from the end of the span. Defaults to `0`. ~~int~~ |
-## AttributeRuler.add_patterns {#add_patterns tag="method"}
+## AttributeRuler.add_patterns {id="add_patterns",tag="method"}
> #### Example
>
@@ -116,7 +116,7 @@ keys `"patterns"`, `"attrs"` and `"index"`, which match the arguments of
| ---------- | -------------------------------------------------------------------------- |
| `patterns` | The patterns to add. ~~Iterable[Dict[str, Union[List[dict], dict, int]]]~~ |
-## AttributeRuler.patterns {#patterns tag="property"}
+## AttributeRuler.patterns {id="patterns",tag="property"}
Get all patterns that have been added to the attribute ruler in the
`patterns_dict` format accepted by
@@ -126,7 +126,7 @@ Get all patterns that have been added to the attribute ruler in the
| ----------- | -------------------------------------------------------------------------------------------- |
| **RETURNS** | The patterns added to the attribute ruler. ~~List[Dict[str, Union[List[dict], dict, int]]]~~ |
-## AttributeRuler.initialize {#initialize tag="method"}
+## AttributeRuler.initialize {id="initialize",tag="method"}
Initialize the component with data and used before training to load in rules
from a file. This method is typically called by
@@ -160,7 +160,7 @@ config.
| `tag_map` | The tag map that maps fine-grained tags to coarse-grained tags and morphological features. Defaults to `None`. ~~Optional[Dict[str, Dict[Union[int, str], Union[int, str]]]]~~ |
| `morph_rules` | The morph rules that map token text and fine-grained tags to coarse-grained tags, lemmas and morphological features. Defaults to `None`. ~~Optional[Dict[str, Dict[str, Dict[Union[int, str], Union[int, str]]]]]~~ |
-## AttributeRuler.load_from_tag_map {#load_from_tag_map tag="method"}
+## AttributeRuler.load_from_tag_map {id="load_from_tag_map",tag="method"}
Load attribute ruler patterns from a tag map.
@@ -168,7 +168,7 @@ Load attribute ruler patterns from a tag map.
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `tag_map` | The tag map that maps fine-grained tags to coarse-grained tags and morphological features. ~~Dict[str, Dict[Union[int, str], Union[int, str]]]~~ |
-## AttributeRuler.load_from_morph_rules {#load_from_morph_rules tag="method"}
+## AttributeRuler.load_from_morph_rules {id="load_from_morph_rules",tag="method"}
Load attribute ruler patterns from morph rules.
@@ -176,7 +176,7 @@ Load attribute ruler patterns from morph rules.
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `morph_rules` | The morph rules that map token text and fine-grained tags to coarse-grained tags, lemmas and morphological features. ~~Dict[str, Dict[str, Dict[Union[int, str], Union[int, str]]]]~~ |
-## AttributeRuler.to_disk {#to_disk tag="method"}
+## AttributeRuler.to_disk {id="to_disk",tag="method"}
Serialize the pipe to disk.
@@ -193,7 +193,7 @@ Serialize the pipe to disk.
| _keyword-only_ | |
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
-## AttributeRuler.from_disk {#from_disk tag="method"}
+## AttributeRuler.from_disk {id="from_disk",tag="method"}
Load the pipe from disk. Modifies the object in place and returns it.
@@ -211,7 +211,7 @@ Load the pipe from disk. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The modified `AttributeRuler` object. ~~AttributeRuler~~ |
-## AttributeRuler.to_bytes {#to_bytes tag="method"}
+## AttributeRuler.to_bytes {id="to_bytes",tag="method"}
> #### Example
>
@@ -228,7 +228,7 @@ Serialize the pipe to a bytestring.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The serialized form of the `AttributeRuler` object. ~~bytes~~ |
-## AttributeRuler.from_bytes {#from_bytes tag="method"}
+## AttributeRuler.from_bytes {id="from_bytes",tag="method"}
Load the pipe from a bytestring. Modifies the object in place and returns it.
@@ -247,7 +247,7 @@ Load the pipe from a bytestring. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The `AttributeRuler` object. ~~AttributeRuler~~ |
-## Serialization fields {#serialization-fields}
+## Serialization fields {id="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
diff --git a/website/docs/api/attributes.mdx b/website/docs/api/attributes.mdx
new file mode 100644
index 000000000..3142b741d
--- /dev/null
+++ b/website/docs/api/attributes.mdx
@@ -0,0 +1,77 @@
+---
+title: Attributes
+teaser: Token attributes
+source: spacy/attrs.pyx
+---
+
+[Token](/api/token) attributes are specified using internal IDs in many places
+including:
+
+- [`Matcher` patterns](/api/matcher#patterns),
+- [`Doc.to_array`](/api/doc#to_array) and
+ [`Doc.from_array`](/api/doc#from_array)
+- [`Doc.has_annotation`](/api/doc#has_annotation)
+- [`MultiHashEmbed`](/api/architectures#MultiHashEmbed) Tok2Vec architecture
+ `attrs`
+
+> ```python
+> import spacy
+> from spacy.attrs import DEP
+>
+> nlp = spacy.blank("en")
+> doc = nlp("There are many attributes.")
+>
+> # DEP always has the same internal value
+> assert DEP == 76
+>
+> # "DEP" is automatically converted to DEP
+> assert DEP == nlp.vocab.strings["DEP"]
+> assert doc.has_annotation(DEP) == doc.has_annotation("DEP")
+>
+> # look up IDs in spacy.attrs.IDS
+> from spacy.attrs import IDS
+> assert IDS["DEP"] == DEP
+> ```
+
+All methods automatically convert between the string version of an ID (`"DEP"`)
+and the internal integer symbols (`DEP`). The internal IDs can be imported from
+`spacy.attrs` or retrieved from the [`StringStore`](/api/stringstore). A map
+from string attribute names to internal attribute IDs is stored in
+`spacy.attrs.IDS`.
+
+The corresponding [`Token` object attributes](/api/token#attributes) can be
+accessed using the same names in lowercase, e.g. `token.orth` or `token.length`.
+For attributes that represent string values, the internal integer ID is accessed
+as `Token.attr`, e.g. `token.dep`, while the string value can be retrieved by
+appending `_` as in `token.dep_`.
+
+| Attribute | Description |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DEP` | The token's dependency label. ~~str~~ |
+| `ENT_ID` | The token's entity ID (`ent_id`). ~~str~~ |
+| `ENT_IOB` | The IOB part of the token's entity tag. Uses custom integer vaues rather than the string store: unset is `0`, `I` is `1`, `O` is `2`, and `B` is `3`. ~~str~~ |
+| `ENT_KB_ID` | The token's entity knowledge base ID. ~~str~~ |
+| `ENT_TYPE` | The token's entity label. ~~str~~ |
+| `IS_ALPHA` | Token text consists of alphabetic characters. ~~bool~~ |
+| `IS_ASCII` | Token text consists of ASCII characters. ~~bool~~ |
+| `IS_DIGIT` | Token text consists of digits. ~~bool~~ |
+| `IS_LOWER` | Token text is in lowercase. ~~bool~~ |
+| `IS_PUNCT` | Token is punctuation. ~~bool~~ |
+| `IS_SPACE` | Token is whitespace. ~~bool~~ |
+| `IS_STOP` | Token is a stop word. ~~bool~~ |
+| `IS_TITLE` | Token text is in titlecase. ~~bool~~ |
+| `IS_UPPER` | Token text is in uppercase. ~~bool~~ |
+| `LEMMA` | The token's lemma. ~~str~~ |
+| `LENGTH` | The length of the token text. ~~int~~ |
+| `LIKE_EMAIL` | Token text resembles an email address. ~~bool~~ |
+| `LIKE_NUM` | Token text resembles a number. ~~bool~~ |
+| `LIKE_URL` | Token text resembles a URL. ~~bool~~ |
+| `LOWER` | The lowercase form of the token text. ~~str~~ |
+| `MORPH` | The token's morphological analysis. ~~MorphAnalysis~~ |
+| `NORM` | The normalized form of the token text. ~~str~~ |
+| `ORTH` | The exact verbatim text of a token. ~~str~~ |
+| `POS` | The token's universal part of speech (UPOS). ~~str~~ |
+| `SENT_START` | Token is start of sentence. ~~bool~~ |
+| `SHAPE` | The token's shape. ~~str~~ |
+| `SPACY` | Token has a trailing space. ~~bool~~ |
+| `TAG` | The token's fine-grained part of speech. ~~str~~ |
diff --git a/website/docs/api/cli.md b/website/docs/api/cli.mdx
similarity index 75%
rename from website/docs/api/cli.md
rename to website/docs/api/cli.mdx
index 89e2e87d9..ca4023101 100644
--- a/website/docs/api/cli.md
+++ b/website/docs/api/cli.mdx
@@ -12,10 +12,12 @@ menu:
- ['train', 'train']
- ['pretrain', 'pretrain']
- ['evaluate', 'evaluate']
+ - ['benchmark', 'benchmark']
+ - ['apply', 'apply']
+ - ['find-threshold', 'find-threshold']
- ['assemble', 'assemble']
- ['package', 'package']
- ['project', 'project']
- - ['ray', 'ray']
- ['huggingface-hub', 'huggingface-hub']
---
@@ -25,7 +27,7 @@ a list of available commands, you can type `python -m spacy --help`. You can
also add the `--help` flag to any command or subcommand to see the description,
available arguments and usage.
-## download {#download tag="command"}
+## download {id="download",tag="command"}
Download [trained pipelines](/usage/models) for spaCy. The downloader finds the
best-matching compatible version and uses `pip install` to download the Python
@@ -43,7 +45,7 @@ pipeline name to be specified with its version (e.g. `en_core_web_sm-3.0.0`).
> will also allow you to add it as a versioned package dependency to your
> project.
-```cli
+```bash
$ python -m spacy download [model] [--direct] [--sdist] [pip_args]
```
@@ -53,40 +55,41 @@ $ python -m spacy download [model] [--direct] [--sdist] [pip_args]
| `--direct`, `-D` | Force direct download of exact package version. ~~bool (flag)~~ |
| `--sdist`, `-S` 3 | Download the source package (`.tar.gz` archive) instead of the default pre-built binary wheel. ~~bool (flag)~~ |
| `--help`, `-h` | Show help message and available arguments. ~~bool (flag)~~ |
-| pip args 2.1 | Additional installation options to be passed to `pip install` when installing the pipeline package. For example, `--user` to install to the user home directory or `--no-deps` to not install package dependencies. ~~Any (option/flag)~~ |
+| pip args | Additional installation options to be passed to `pip install` when installing the pipeline package. For example, `--user` to install to the user home directory or `--no-deps` to not install package dependencies. ~~Any (option/flag)~~ |
| **CREATES** | The installed pipeline package in your `site-packages` directory. |
-## info {#info tag="command"}
+## info {id="info",tag="command"}
Print information about your spaCy installation, trained pipelines and local
setup, and generate [Markdown](https://en.wikipedia.org/wiki/Markdown)-formatted
markup to copy-paste into
[GitHub issues](https://github.com/explosion/spaCy/issues).
-```cli
+```bash
$ python -m spacy info [--markdown] [--silent] [--exclude]
```
> #### Example
>
-> ```cli
+> ```bash
> $ python -m spacy info en_core_web_lg --markdown
> ```
-```cli
+```bash
$ python -m spacy info [model] [--markdown] [--silent] [--exclude]
```
-| Name | Description |
-| ------------------------------------------------ | --------------------------------------------------------------------------------------------- |
-| `model` | A trained pipeline, i.e. package name or path (optional). ~~Optional[str] \(option)~~ |
-| `--markdown`, `-md` | Print information as Markdown. ~~bool (flag)~~ |
-| `--silent`, `-s` 2.0.12 | Don't print anything, just return the values. ~~bool (flag)~~ |
-| `--exclude`, `-e` | Comma-separated keys to exclude from the print-out. Defaults to `"labels"`. ~~Optional[str]~~ |
-| `--help`, `-h` | Show help message and available arguments. ~~bool (flag)~~ |
-| **PRINTS** | Information about your spaCy installation. |
+| Name | Description |
+| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `model` | A trained pipeline, i.e. package name or path (optional). ~~Optional[str] \(option)~~ |
+| `--markdown`, `-md` | Print information as Markdown. ~~bool (flag)~~ |
+| `--silent`, `-s` | Don't print anything, just return the values. ~~bool (flag)~~ |
+| `--exclude`, `-e` | Comma-separated keys to exclude from the print-out. Defaults to `"labels"`. ~~Optional[str]~~ |
+| `--url`, `-u` 3.5.0 | Print the URL to download the most recent compatible version of the pipeline. Requires a pipeline name. ~~bool (flag)~~ |
+| `--help`, `-h` | Show help message and available arguments. ~~bool (flag)~~ |
+| **PRINTS** | Information about your spaCy installation. |
-## validate {#validate new="2" tag="command"}
+## validate {id="validate",version="2",tag="command"}
Find all trained pipeline packages installed in the current environment and
check whether they are compatible with the currently installed version of spaCy.
@@ -101,7 +104,7 @@ compatible versions and command for updating are shown.
> suite, to ensure all packages are up to date before proceeding. If
> incompatible packages are found, it will return `1`.
-```cli
+```bash
$ python -m spacy validate
```
@@ -109,12 +112,12 @@ $ python -m spacy validate
| ---------- | -------------------------------------------------------------------- |
| **PRINTS** | Details about the compatibility of your installed pipeline packages. |
-## init {#init new="3"}
+## init {id="init",version="3"}
The `spacy init` CLI includes helpful commands for initializing training config
files and pipeline directories.
-### init config {#init-config new="3" tag="command"}
+### init config {id="init-config",version="3",tag="command"}
Initialize and save a [`config.cfg` file](/usage/training#config) using the
**recommended settings** for your use case. It works just like the
@@ -126,11 +129,11 @@ customize those settings in your config file later.
> #### Example
>
-> ```cli
+> ```bash
> $ python -m spacy init config config.cfg --lang en --pipeline ner,textcat --optimize accuracy
> ```
-```cli
+```bash
$ python -m spacy init config [output_file] [--lang] [--pipeline] [--optimize] [--gpu] [--pretraining] [--force]
```
@@ -146,7 +149,7 @@ $ python -m spacy init config [output_file] [--lang] [--pipeline] [--optimize] [
| `--help`, `-h` | Show help message and available arguments. ~~bool (flag)~~ |
| **CREATES** | The config file for training. |
-### init fill-config {#init-fill-config new="3"}
+### init fill-config {id="init-fill-config",version="3"}
Auto-fill a partial [.cfg file](/usage/training#config) with **all default
values**, e.g. a config generated with the
@@ -160,15 +163,15 @@ validation error with more details.
> #### Example
>
-> ```cli
+> ```bash
> $ python -m spacy init fill-config base.cfg config.cfg --diff
> ```
>
> #### Example diff
>
-> 
+> 
-```cli
+```bash
$ python -m spacy init fill-config [base_path] [output_file] [--diff]
```
@@ -182,7 +185,7 @@ $ python -m spacy init fill-config [base_path] [output_file] [--diff]
| `--help`, `-h` | Show help message and available arguments. ~~bool (flag)~~ |
| **CREATES** | Complete and auto-filled config file for training. |
-### init vectors {#init-vectors new="3" tag="command"}
+### init vectors {id="init-vectors",version="3",tag="command"}
Convert [word vectors](/usage/linguistic-features#vectors-similarity) for use
with spaCy. Will export an `nlp` object that you can use in the
@@ -197,7 +200,7 @@ This functionality was previously available as part of the command `init-model`.
-```cli
+```bash
$ python -m spacy init vectors [lang] [vectors_loc] [output_dir] [--prune] [--truncate] [--name] [--verbose]
```
@@ -214,7 +217,7 @@ $ python -m spacy init vectors [lang] [vectors_loc] [output_dir] [--prune] [--tr
| `--help`, `-h` | Show help message and available arguments. ~~bool (flag)~~ |
| **CREATES** | A spaCy pipeline directory containing the vocab and vectors. |
-### init labels {#init-labels new="3" tag="command"}
+### init labels {id="init-labels",version="3",tag="command"}
Generate JSON files for the labels in the data. This helps speed up the training
process, since spaCy won't have to preprocess the data to extract the labels.
@@ -232,7 +235,7 @@ After generating the labels, you can provide them to components that accept a
> path = "corpus/labels/ner.json
> ```
-```cli
+```bash
$ python -m spacy init labels [config_path] [output_path] [--code] [--verbose] [--gpu-id] [overrides]
```
@@ -247,7 +250,7 @@ $ python -m spacy init labels [config_path] [output_path] [--code] [--verbose] [
| overrides | Config parameters to override. Should be options starting with `--` that correspond to the config section and value to override, e.g. `--paths.train ./train.spacy`. ~~Any (option/flag)~~ |
| **CREATES** | The label files. |
-## convert {#convert tag="command"}
+## convert {id="convert",tag="command"}
Convert files into spaCy's
[binary training data format](/api/data-formats#binary-training), a serialized
@@ -255,28 +258,28 @@ Convert files into spaCy's
management functions. The converter can be specified on the command line, or
chosen based on the file extension of the input file.
-```cli
+```bash
$ python -m spacy convert [input_file] [output_dir] [--converter] [--file-type] [--n-sents] [--seg-sents] [--base] [--morphology] [--merge-subtokens] [--ner-map] [--lang]
```
-| Name | Description |
-| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `input_path` | Input file or directory. ~~Path (positional)~~ |
-| `output_dir` | Output directory for converted file. Defaults to `"-"`, meaning data will be written to `stdout`. ~~Optional[Path] \(option)~~ |
-| `--converter`, `-c` 2 | Name of converter to use (see below). ~~str (option)~~ |
-| `--file-type`, `-t` 2.1 | Type of file to create. Either `spacy` (default) for binary [`DocBin`](/api/docbin) data or `json` for v2.x JSON format. ~~str (option)~~ |
-| `--n-sents`, `-n` | Number of sentences per document. Supported for: `conll`, `conllu`, `iob`, `ner` ~~int (option)~~ |
-| `--seg-sents`, `-s` 2.2 | Segment sentences. Supported for: `conll`, `ner` ~~bool (flag)~~ |
-| `--base`, `-b`, `--model` | Trained spaCy pipeline for sentence segmentation to use as base (for `--seg-sents`). ~~Optional[str](option)~~ |
-| `--morphology`, `-m` | Enable appending morphology to tags. Supported for: `conllu` ~~bool (flag)~~ |
-| `--merge-subtokens`, `-T` | Merge CoNLL-U subtokens ~~bool (flag)~~ |
-| `--ner-map`, `-nm` | NER tag mapping (as JSON-encoded dict of entity types). Supported for: `conllu` ~~Optional[Path](option)~~ |
-| `--lang`, `-l` 2.1 | Language code (if tokenizer required). ~~Optional[str] \(option)~~ |
-| `--concatenate`, `-C` | Concatenate output to a single file ~~bool (flag)~~ |
-| `--help`, `-h` | Show help message and available arguments. ~~bool (flag)~~ |
-| **CREATES** | Binary [`DocBin`](/api/docbin) training data that can be used with [`spacy train`](/api/cli#train). |
+| Name | Description |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `input_path` | Input file or directory. ~~Path (positional)~~ |
+| `output_dir` | Output directory for converted file. Defaults to `"-"`, meaning data will be written to `stdout`. ~~Optional[Path] \(option)~~ |
+| `--converter`, `-c` | Name of converter to use (see below). ~~str (option)~~ |
+| `--file-type`, `-t` | Type of file to create. Either `spacy` (default) for binary [`DocBin`](/api/docbin) data or `json` for v2.x JSON format. ~~str (option)~~ |
+| `--n-sents`, `-n` | Number of sentences per document. Supported for: `conll`, `conllu`, `iob`, `ner` ~~int (option)~~ |
+| `--seg-sents`, `-s` | Segment sentences. Supported for: `conll`, `ner` ~~bool (flag)~~ |
+| `--base`, `-b`, `--model` | Trained spaCy pipeline for sentence segmentation to use as base (for `--seg-sents`). ~~Optional[str](option)~~ |
+| `--morphology`, `-m` | Enable appending morphology to tags. Supported for: `conllu` ~~bool (flag)~~ |
+| `--merge-subtokens`, `-T` | Merge CoNLL-U subtokens ~~bool (flag)~~ |
+| `--ner-map`, `-nm` | NER tag mapping (as JSON-encoded dict of entity types). Supported for: `conllu` ~~Optional[Path](option)~~ |
+| `--lang`, `-l` | Language code (if tokenizer required). ~~Optional[str] \(option)~~ |
+| `--concatenate`, `-C` | Concatenate output to a single file ~~bool (flag)~~ |
+| `--help`, `-h` | Show help message and available arguments. ~~bool (flag)~~ |
+| **CREATES** | Binary [`DocBin`](/api/docbin) training data that can be used with [`spacy train`](/api/cli#train). |
-### Converters {#converters}
+### Converters {id="converters"}
| ID | Description |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -286,12 +289,12 @@ $ python -m spacy convert [input_file] [output_dir] [--converter] [--file-type]
| `ner` / `conll` | NER with IOB/IOB2/BILUO tags, one token per line with columns separated by whitespace. The first column is the token and the final column is the NER tag. Sentences are separated by blank lines and documents are separated by the line `-DOCSTART- -X- O O`. Supports CoNLL 2003 NER format. See [sample data](%%GITHUB_SPACY/extra/example_data/ner_example_data). |
| `iob` | NER with IOB/IOB2/BILUO tags, one sentence per line with tokens separated by whitespace and annotation separated by `\|`, either `word\|B-ENT`or`word\|POS\|B-ENT`. See [sample data](%%GITHUB_SPACY/extra/example_data/ner_example_data). |
-## debug {#debug new="3"}
+## debug {id="debug",version="3"}
The `spacy debug` CLI includes helpful commands for debugging and profiling your
configs, data and implementations.
-### debug config {#debug-config new="3" tag="command"}
+### debug config {id="debug-config",version="3",tag="command"}
Debug a [`config.cfg` file](/usage/training#config) and show validation errors.
The command will create all objects in the tree and validate them. Note that
@@ -301,13 +304,13 @@ errors at once and some issues are only shown once previous errors have been
fixed. To auto-fill a partial config and save the result, you can use the
[`init fill-config`](/api/cli#init-fill-config) command.
-```cli
+```bash
$ python -m spacy debug config [config_path] [--code] [--show-functions] [--show-variables] [overrides]
```
> #### Example
>
-> ```cli
+> ```bash
> $ python -m spacy debug config config.cfg
> ```
@@ -331,7 +334,7 @@ python -m spacy init fill-config tmp/starter-config_invalid.cfg tmp/starter-conf
-```cli
+```bash
$ python -m spacy debug config ./config.cfg --show-functions --show-variables
```
@@ -451,7 +454,7 @@ File /path/to/thinc/thinc/schedules.py (line 91)
| overrides | Config parameters to override. Should be options starting with `--` that correspond to the config section and value to override, e.g. `--paths.train ./train.spacy`. ~~Any (option/flag)~~ |
| **PRINTS** | Config validation errors, if available. |
-### debug data {#debug-data tag="command"}
+### debug data {id="debug-data",tag="command"}
Analyze, debug and validate your training and development data. Get useful
stats, and find problems like invalid entity annotations, cyclic dependencies,
@@ -466,13 +469,24 @@ takes the same arguments as `train` and reads settings off the
-```cli
+
+
+If your pipeline contains a `spancat` component, then this command will also
+report span characteristics such as the average span length and the span (or
+span boundary) distinctiveness. The distinctiveness measure shows how different
+the tokens are with respect to the rest of the corpus using the KL-divergence of
+the token distributions. To learn more, you can check out Papay et al.'s work on
+[_Dissecting Span Identification Tasks with Performance Prediction_ (EMNLP 2020)](https://aclanthology.org/2020.emnlp-main.396/).
+
+
+
+```bash
$ python -m spacy debug data [config_path] [--code] [--ignore-warnings] [--verbose] [--no-format] [overrides]
```
> #### Example
>
-> ```cli
+> ```bash
> $ python -m spacy debug data ./config.cfg
> ```
@@ -626,7 +640,236 @@ will not be available.
| overrides | Config parameters to override. Should be options starting with `--` that correspond to the config section and value to override, e.g. `--paths.train ./train.spacy`. ~~Any (option/flag)~~ |
| **PRINTS** | Debugging information. |
-### debug profile {#debug-profile tag="command"}
+### debug diff-config {id="debug-diff",tag="command"}
+
+Show a diff of a config file with respect to spaCy's defaults or another config
+file. If additional settings were used in the creation of the config file, then
+you must supply these as extra parameters to the command when comparing to the
+default settings. The generated diff can also be used when posting to the
+discussion forum to provide more information for the maintainers.
+
+```bash
+$ python -m spacy debug diff-config [config_path] [--compare-to] [--optimize] [--gpu] [--pretraining] [--markdown]
+```
+
+> #### Example
+>
+> ```bash
+> $ python -m spacy debug diff-config ./config.cfg
+> ```
+
+
+
+```
+ℹ Found user-defined language: 'en'
+ℹ Found user-defined pipelines: ['tok2vec', 'tagger', 'parser',
+'ner']
+[paths]
++ train = "./data/train.spacy"
++ dev = "./data/dev.spacy"
+- train = null
+- dev = null
+vectors = null
+init_tok2vec = null
+
+[system]
+gpu_allocator = null
++ seed = 42
+- seed = 0
+
+[nlp]
+lang = "en"
+pipeline = ["tok2vec","tagger","parser","ner"]
+batch_size = 1000
+disabled = []
+before_creation = null
+after_creation = null
+after_pipeline_creation = null
+tokenizer = {"@tokenizers":"spacy.Tokenizer.v1"}
+
+[components]
+
+[components.ner]
+factory = "ner"
+incorrect_spans_key = null
+moves = null
+scorer = {"@scorers":"spacy.ner_scorer.v1"}
+update_with_oracle_cut_size = 100
+
+[components.ner.model]
+@architectures = "spacy.TransitionBasedParser.v2"
+state_type = "ner"
+extra_state_tokens = false
+- hidden_width = 64
++ hidden_width = 36
+maxout_pieces = 2
+use_upper = true
+nO = null
+
+[components.ner.model.tok2vec]
+@architectures = "spacy.Tok2VecListener.v1"
+width = ${components.tok2vec.model.encode.width}
+upstream = "*"
+
+[components.parser]
+factory = "parser"
+learn_tokens = false
+min_action_freq = 30
+moves = null
+scorer = {"@scorers":"spacy.parser_scorer.v1"}
+update_with_oracle_cut_size = 100
+
+[components.parser.model]
+@architectures = "spacy.TransitionBasedParser.v2"
+state_type = "parser"
+extra_state_tokens = false
+hidden_width = 128
+maxout_pieces = 3
+use_upper = true
+nO = null
+
+[components.parser.model.tok2vec]
+@architectures = "spacy.Tok2VecListener.v1"
+width = ${components.tok2vec.model.encode.width}
+upstream = "*"
+
+[components.tagger]
+factory = "tagger"
+neg_prefix = "!"
+overwrite = false
+scorer = {"@scorers":"spacy.tagger_scorer.v1"}
+
+[components.tagger.model]
+@architectures = "spacy.Tagger.v1"
+nO = null
+
+[components.tagger.model.tok2vec]
+@architectures = "spacy.Tok2VecListener.v1"
+width = ${components.tok2vec.model.encode.width}
+upstream = "*"
+
+[components.tok2vec]
+factory = "tok2vec"
+
+[components.tok2vec.model]
+@architectures = "spacy.Tok2Vec.v2"
+
+[components.tok2vec.model.embed]
+@architectures = "spacy.MultiHashEmbed.v2"
+width = ${components.tok2vec.model.encode.width}
+attrs = ["NORM","PREFIX","SUFFIX","SHAPE"]
+rows = [5000,2500,2500,2500]
+include_static_vectors = false
+
+[components.tok2vec.model.encode]
+@architectures = "spacy.MaxoutWindowEncoder.v2"
+width = 96
+depth = 4
+window_size = 1
+maxout_pieces = 3
+
+[corpora]
+
+[corpora.dev]
+@readers = "spacy.Corpus.v1"
+path = ${paths.dev}
+max_length = 0
+gold_preproc = false
+limit = 0
+augmenter = null
+
+[corpora.train]
+@readers = "spacy.Corpus.v1"
+path = ${paths.train}
+max_length = 0
+gold_preproc = false
+limit = 0
+augmenter = null
+
+[training]
+dev_corpus = "corpora.dev"
+train_corpus = "corpora.train"
+seed = ${system.seed}
+gpu_allocator = ${system.gpu_allocator}
+dropout = 0.1
+accumulate_gradient = 1
+patience = 1600
+max_epochs = 0
+max_steps = 20000
+eval_frequency = 200
+frozen_components = []
+annotating_components = []
+before_to_disk = null
+
+[training.batcher]
+@batchers = "spacy.batch_by_words.v1"
+discard_oversize = false
+tolerance = 0.2
+get_length = null
+
+[training.batcher.size]
+@schedules = "compounding.v1"
+start = 100
+stop = 1000
+compound = 1.001
+t = 0.0
+
+[training.logger]
+@loggers = "spacy.ConsoleLogger.v1"
+progress_bar = false
+
+[training.optimizer]
+@optimizers = "Adam.v1"
+beta1 = 0.9
+beta2 = 0.999
+L2_is_weight_decay = true
+L2 = 0.01
+grad_clip = 1.0
+use_averages = false
+eps = 0.00000001
+learn_rate = 0.001
+
+[training.score_weights]
+tag_acc = 0.33
+dep_uas = 0.17
+dep_las = 0.17
+dep_las_per_type = null
+sents_p = null
+sents_r = null
+sents_f = 0.0
+ents_f = 0.33
+ents_p = 0.0
+ents_r = 0.0
+ents_per_type = null
+
+[pretraining]
+
+[initialize]
+vectors = ${paths.vectors}
+init_tok2vec = ${paths.init_tok2vec}
+vocab_data = null
+lookups = null
+before_init = null
+after_init = null
+
+[initialize.components]
+
+[initialize.tokenizer]
+```
+
+
+
+| Name | Description |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `config_path` | Path to [training config](/api/data-formats#config) file containing all settings and hyperparameters. ~~Union[Path, str] \(positional)~~ |
+| `compare_to` | Path to another config file to diff against, or `None` to compare against default settings. ~~Optional[Union[Path, str] \(option)~~ |
+| `optimize`, `-o` | `"efficiency"` or `"accuracy"`. Whether the config was optimized for efficiency (faster inference, smaller model, lower memory consumption) or higher accuracy (potentially larger and slower model). Only relevant when comparing against a default config. Defaults to `"efficiency"`. ~~str (option)~~ |
+| `gpu`, `-G` | Whether the config was made to run on a GPU. Only relevant when comparing against a default config. ~~bool (flag)~~ |
+| `pretraining`, `-pt` | Include config for pretraining (with [`spacy pretrain`](/api/cli#pretrain)). Only relevant when comparing against a default config. Defaults to `False`. ~~bool (flag)~~ |
+| `markdown`, `-md` | Generate Markdown for Github issues. Defaults to `False`. ~~bool (flag)~~ |
+| **PRINTS** | Diff between the two config files. |
+
+### debug profile {id="debug-profile",tag="command"}
Profile which functions take the most time in a spaCy pipeline. Input should be
formatted as one JSON object per line with a key `"text"`. It can either be
@@ -640,7 +883,7 @@ The `profile` command is now available as a subcommand of `spacy debug`.
-```cli
+```bash
$ python -m spacy debug profile [model] [inputs] [--n-texts]
```
@@ -652,12 +895,12 @@ $ python -m spacy debug profile [model] [inputs] [--n-texts]
| `--help`, `-h` | Show help message and available arguments. ~~bool (flag)~~ |
| **PRINTS** | Profiling information for the pipeline. |
-### debug model {#debug-model new="3" tag="command"}
+### debug model {id="debug-model",version="3",tag="command"}
Debug a Thinc [`Model`](https://thinc.ai/docs/api-model) by running it on a
sample text and checking how it updates its internal weights and parameters.
-```cli
+```bash
$ python -m spacy debug model [config_path] [component] [--layers] [--dimensions] [--parameters] [--gradients] [--attributes] [--print-step0] [--print-step1] [--print-step2] [--print-step3] [--gpu-id]
```
@@ -668,7 +911,7 @@ model ("Step 0"), which helps us to understand the internal structure of the
Neural Network, and to focus on specific layers that we want to inspect further
(see next example).
-```cli
+```bash
$ python -m spacy debug model ./config.cfg tagger -P0
```
@@ -714,7 +957,7 @@ an all-zero matrix determined by the `nO` and `nI` dimensions. After a first
training step (Step 2), this matrix has clearly updated its values through the
training feedback loop.
-```cli
+```bash
$ python -m spacy debug model ./config.cfg tagger -l "5,15" -DIM -PAR -P0 -P1 -P2
```
@@ -775,7 +1018,7 @@ $ python -m spacy debug model ./config.cfg tagger -l "5,15" -DIM -PAR -P0 -P1 -P
| overrides | Config parameters to override. Should be options starting with `--` that correspond to the config section and value to override, e.g. `--paths.train ./train.spacy`. ~~Any (option/flag)~~ |
| **PRINTS** | Debugging information. |
-## train {#train tag="command"}
+## train {id="train",tag="command"}
Train a pipeline. Expects data in spaCy's
[binary format](/api/data-formats#training) and a
@@ -801,11 +1044,11 @@ in the section `[paths]`.
> #### Example
>
-> ```cli
+> ```bash
> $ python -m spacy train config.cfg --output ./output --paths.train ./train --paths.dev ./dev
> ```
-```cli
+```bash
$ python -m spacy train [config_path] [--output] [--code] [--verbose] [--gpu-id] [overrides]
```
@@ -820,7 +1063,7 @@ $ python -m spacy train [config_path] [--output] [--code] [--verbose] [--gpu-id]
| overrides | Config parameters to override. Should be options starting with `--` that correspond to the config section and value to override, e.g. `--paths.train ./train.spacy`. ~~Any (option/flag)~~ |
| **CREATES** | The final trained pipeline and the best trained pipeline. |
-### Calling the training function from Python {#train-function new="3.2"}
+### Calling the training function from Python {id="train-function",version="3.2"}
The training CLI exposes a `train` helper function that lets you run the
training just like `spacy train`. Usually it's easier to use the command line
@@ -843,7 +1086,7 @@ directly, but if you need to kick off training from code this is how to do it.
| `use_gpu` | Which GPU to use. Defaults to -1 for no GPU. ~~int~~ |
| `overrides` | Values to override config settings. ~~Dict[str, Any]~~ |
-## pretrain {#pretrain new="2.1" tag="command,experimental"}
+## pretrain {id="pretrain",version="2.1",tag="command,experimental"}
Pretrain the "token to vector" ([`Tok2vec`](/api/tok2vec)) layer of pipeline
components on raw text, using an approximate language-modeling objective.
@@ -871,11 +1114,11 @@ auto-generated by setting `--pretraining` on
> #### Example
>
-> ```cli
+> ```bash
> $ python -m spacy pretrain config.cfg ./output_pretrain --paths.raw_text ./data.jsonl
> ```
-```cli
+```bash
$ python -m spacy pretrain [config_path] [output_dir] [--code] [--resume-path] [--epoch-resume] [--gpu-id] [overrides]
```
@@ -891,10 +1134,21 @@ $ python -m spacy pretrain [config_path] [output_dir] [--code] [--resume-path] [
| overrides | Config parameters to override. Should be options starting with `--` that correspond to the config section and value to override, e.g. `--training.dropout 0.2`. ~~Any (option/flag)~~ |
| **CREATES** | The pretrained weights that can be used to initialize `spacy train`. |
-## evaluate {#evaluate new="2" tag="command"}
+## evaluate {id="evaluate",version="2",tag="command"}
-Evaluate a trained pipeline. Expects a loadable spaCy pipeline (package name or
-path) and evaluation data in the
+The `evaluate` subcommand is superseded by
+[`spacy benchmark accuracy`](#benchmark-accuracy). `evaluate` is provided as an
+alias to `benchmark accuracy` for compatibility.
+
+## benchmark {id="benchmark", version="3.5"}
+
+The `spacy benchmark` CLI includes commands for benchmarking the accuracy and
+speed of your spaCy pipelines.
+
+### accuracy {id="benchmark-accuracy", version="3.5", tag="command"}
+
+Evaluate the accuracy of a trained pipeline. Expects a loadable spaCy pipeline
+(package name or path) and evaluation data in the
[binary `.spacy` format](/api/data-formats#binary-training). The
`--gold-preproc` option sets up the evaluation examples with gold-standard
sentences and tokens for the predictions. Gold preprocessing helps the
@@ -904,8 +1158,8 @@ skew. To render a sample of dependency parses in a HTML file using the
[displaCy visualizations](/usage/visualizers), set as output directory as the
`--displacy-path` argument.
-```cli
-$ python -m spacy evaluate [model] [data_path] [--output] [--code] [--gold-preproc] [--gpu-id] [--displacy-path] [--displacy-limit]
+```bash
+$ python -m spacy benchmark accuracy [model] [data_path] [--output] [--code] [--gold-preproc] [--gpu-id] [--displacy-path] [--displacy-limit]
```
| Name | Description |
@@ -921,7 +1175,100 @@ $ python -m spacy evaluate [model] [data_path] [--output] [--code] [--gold-prepr
| `--help`, `-h` | Show help message and available arguments. ~~bool (flag)~~ |
| **CREATES** | Training results and optional metrics and visualizations. |
-## assemble {#assemble tag="command"}
+### speed {id="benchmark-speed", version="3.5", tag="command"}
+
+Benchmark the speed of a trained pipeline with a 95% confidence interval.
+Expects a loadable spaCy pipeline (package name or path) and benchmark data in
+the [binary `.spacy` format](/api/data-formats#binary-training). The pipeline is
+warmed up before any measurements are taken.
+
+```cli
+$ python -m spacy benchmark speed [model] [data_path] [--batch_size] [--no-shuffle] [--gpu-id] [--batches] [--warmup]
+```
+
+| Name | Description |
+| -------------------- | -------------------------------------------------------------------------------------------------------- |
+| `model` | Pipeline to benchmark the speed of. Can be a package or a path to a data directory. ~~str (positional)~~ |
+| `data_path` | Location of benchmark data in spaCy's [binary format](/api/data-formats#training). ~~Path (positional)~~ |
+| `--batch-size`, `-b` | Set the batch size. If not set, the pipeline's batch size is used. ~~Optional[int] \(option)~~ |
+| `--no-shuffle` | Do not shuffle documents in the benchmark data. ~~bool (flag)~~ |
+| `--gpu-id`, `-g` | GPU to use, if any. Defaults to `-1` for CPU. ~~int (option)~~ |
+| `--batches` | Number of batches to benchmark on. Defaults to `50`. ~~Optional[int] \(option)~~ |
+| `--warmup`, `-w` | Iterations over the benchmark data for warmup. Defaults to `3` ~~Optional[int] \(option)~~ |
+| `--help`, `-h` | Show help message and available arguments. ~~bool (flag)~~ |
+| **PRINTS** | Pipeline speed in words per second with a 95% confidence interval. |
+
+## apply {id="apply", version="3.5", tag="command"}
+
+Applies a trained pipeline to data and stores the resulting annotated documents
+in a `DocBin`. The input can be a single file or a directory. The recognized
+input formats are:
+
+1. `.spacy`
+2. `.jsonl` containing a user specified `text_key`
+3. Files with any other extension are assumed to be plain text files containing
+ a single document.
+
+When a directory is provided it is traversed recursively to collect all files.
+
+```bash
+$ python -m spacy apply [model] [data-path] [output-file] [--code] [--text-key] [--force-overwrite] [--gpu-id] [--batch-size] [--n-process]
+```
+
+| Name | Description |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `model` | Pipeline to apply to the data. Can be a package or a path to a data directory. ~~str (positional)~~ |
+| `data_path` | Location of data to be evaluated in spaCy's [binary format](/api/data-formats#training), jsonl, or plain text. ~~Path (positional)~~ |
+| `output-file`, `-o` | Output `DocBin` path. ~~str (positional)~~ |
+| `--code`, `-c` | Path to Python file with additional code to be imported. Allows [registering custom functions](/usage/training#custom-functions) for new architectures. ~~Optional[Path] \(option)~~ |
+| `--text-key`, `-tk` | The key for `.jsonl` files to use to grab the texts from. Defaults to `text`. ~~Optional[str] \(option)~~ |
+| `--force-overwrite`, `-F` | If the provided `output-file` already exists, then force `apply` to overwrite it. If this is `False` (default) then quits with a warning instead. ~~bool (flag)~~ |
+| `--gpu-id`, `-g` | GPU to use, if any. Defaults to `-1` for CPU. ~~int (option)~~ |
+| `--batch-size`, `-b` | Batch size to use for prediction. Defaults to `1`. ~~int (option)~~ |
+| `--n-process`, `-n` | Number of processes to use for prediction. Defaults to `1`. ~~int (option)~~ |
+| `--help`, `-h` | Show help message and available arguments. ~~bool (flag)~~ |
+| **CREATES** | A `DocBin` with the annotations from the `model` for all the files found in `data-path`. |
+
+## find-threshold {id="find-threshold",version="3.5",tag="command"}
+
+Runs prediction trials for a trained model with varying tresholds to maximize
+the specified metric. The search space for the threshold is traversed linearly
+from 0 to 1 in `n_trials` steps. Results are displayed in a table on `stdout`
+(the corresponding API call to `spacy.cli.find_threshold.find_threshold()`
+returns all results).
+
+This is applicable only for components whose predictions are influenced by
+thresholds - e.g. `textcat_multilabel` and `spancat`, but not `textcat`. Note
+that the full path to the corresponding threshold attribute in the config has to
+be provided.
+
+> #### Examples
+>
+> ```bash
+> # For textcat_multilabel:
+> $ python -m spacy find-threshold my_nlp data.spacy textcat_multilabel threshold cats_macro_f
+> ```
+>
+> ```bash
+> # For spancat:
+> $ python -m spacy find-threshold my_nlp data.spacy spancat threshold spans_sc_f
+> ```
+
+| Name | Description |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `model` | Pipeline to evaluate. Can be a package or a path to a data directory. ~~str (positional)~~ |
+| `data_path` | Path to file with DocBin with docs to use for threshold search. ~~Path (positional)~~ |
+| `pipe_name` | Name of pipe to examine thresholds for. ~~str (positional)~~ |
+| `threshold_key` | Key of threshold attribute in component's configuration. ~~str (positional)~~ |
+| `scores_key` | Name of score to metric to optimize. ~~str (positional)~~ |
+| `--n_trials`, `-n` | Number of trials to determine optimal thresholds. ~~int (option)~~ |
+| `--code`, `-c` | Path to Python file with additional code to be imported. Allows [registering custom functions](/usage/training#custom-functions) for new architectures. ~~Optional[Path] \(option)~~ |
+| `--gpu-id`, `-g` | GPU to use, if any. Defaults to `-1` for CPU. ~~int (option)~~ |
+| `--gold-preproc`, `-G` | Use gold preprocessing. ~~bool (flag)~~ |
+| `--silent`, `-V`, `-VV` | GPU to use, if any. Defaults to `-1` for CPU. ~~int (option)~~ |
+| `--help`, `-h` | Show help message and available arguments. ~~bool (flag)~~ |
+
+## assemble {id="assemble",tag="command"}
Assemble a pipeline from a config file without additional training. Expects a
[config file](/api/data-formats#config) with all settings and hyperparameters.
@@ -931,11 +1278,11 @@ config.
> #### Example
>
-> ```cli
+> ```bash
> $ python -m spacy assemble config.cfg ./output
> ```
-```cli
+```bash
$ python -m spacy assemble [config_path] [output_dir] [--code] [--verbose] [overrides]
```
@@ -949,7 +1296,7 @@ $ python -m spacy assemble [config_path] [output_dir] [--code] [--verbose] [over
| overrides | Config parameters to override. Should be options starting with `--` that correspond to the config section and value to override, e.g. `--paths.data ./data`. ~~Any (option/flag)~~ |
| **CREATES** | The final assembled pipeline. |
-## package {#package tag="command"}
+## package {id="package",tag="command"}
Generate an installable [Python package](/usage/training#models-generating) from
an existing pipeline data directory. All data files are copied over. If
@@ -975,39 +1322,39 @@ the sdist and wheel by setting `--build sdist,wheel`.
-```cli
+```bash
$ python -m spacy package [input_dir] [output_dir] [--code] [--meta-path] [--create-meta] [--build] [--name] [--version] [--force]
```
> #### Example
>
-> ```cli
+> ```bash
> $ python -m spacy package /input /output
> $ cd /output/en_pipeline-0.0.0
> $ pip install dist/en_pipeline-0.0.0.tar.gz
> ```
-| Name | Description |
-| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `input_dir` | Path to directory containing pipeline data. ~~Path (positional)~~ |
-| `output_dir` | Directory to create package folder in. ~~Path (positional)~~ |
-| `--code`, `-c` 3 | Comma-separated paths to Python files to be included in the package and imported in its `__init__.py`. This allows including [registering functions](/usage/training#custom-functions) and [custom components](/usage/processing-pipelines#custom-components). ~~str (option)~~ |
-| `--meta-path`, `-m` 2 | Path to [`meta.json`](/api/data-formats#meta) file (optional). ~~Optional[Path] \(option)~~ |
-| `--create-meta`, `-C` 2 | Create a `meta.json` file on the command line, even if one already exists in the directory. If an existing file is found, its entries will be shown as the defaults in the command line prompt. ~~bool (flag)~~ |
-| `--build`, `-b` 3 | Comma-separated artifact formats to build. Can be `sdist` (for a `.tar.gz` archive) and/or `wheel` (for a binary `.whl` file), or `none` if you want to run this step manually. The generated artifacts can be installed by `pip install`. Defaults to `sdist`. ~~str (option)~~ |
-| `--name`, `-n` 3 | Package name to override in meta. ~~Optional[str] \(option)~~ |
-| `--version`, `-v` 3 | Package version to override in meta. Useful when training new versions, as it doesn't require editing the meta template. ~~Optional[str] \(option)~~ |
-| `--force`, `-f` | Force overwriting of existing folder in output directory. ~~bool (flag)~~ |
-| `--help`, `-h` | Show help message and available arguments. ~~bool (flag)~~ |
-| **CREATES** | A Python package containing the spaCy pipeline. |
+| Name | Description |
+| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `input_dir` | Path to directory containing pipeline data. ~~Path (positional)~~ |
+| `output_dir` | Directory to create package folder in. ~~Path (positional)~~ |
+| `--code`, `-c` 3 | Comma-separated paths to Python files to be included in the package and imported in its `__init__.py`. This allows including [registering functions](/usage/training#custom-functions) and [custom components](/usage/processing-pipelines#custom-components). ~~str (option)~~ |
+| `--meta-path`, `-m` | Path to [`meta.json`](/api/data-formats#meta) file (optional). ~~Optional[Path] \(option)~~ |
+| `--create-meta`, `-C` | Create a `meta.json` file on the command line, even if one already exists in the directory. If an existing file is found, its entries will be shown as the defaults in the command line prompt. ~~bool (flag)~~ |
+| `--build`, `-b` 3 | Comma-separated artifact formats to build. Can be `sdist` (for a `.tar.gz` archive) and/or `wheel` (for a binary `.whl` file), or `none` if you want to run this step manually. The generated artifacts can be installed by `pip install`. Defaults to `sdist`. ~~str (option)~~ |
+| `--name`, `-n` 3 | Package name to override in meta. ~~Optional[str] \(option)~~ |
+| `--version`, `-v` 3 | Package version to override in meta. Useful when training new versions, as it doesn't require editing the meta template. ~~Optional[str] \(option)~~ |
+| `--force`, `-f` | Force overwriting of existing folder in output directory. ~~bool (flag)~~ |
+| `--help`, `-h` | Show help message and available arguments. ~~bool (flag)~~ |
+| **CREATES** | A Python package containing the spaCy pipeline. |
-## project {#project new="3"}
+## project {id="project",version="3"}
The `spacy project` CLI includes subcommands for working with
[spaCy projects](/usage/projects), end-to-end workflows for building and
deploying custom spaCy pipelines.
-### project clone {#project-clone tag="command"}
+### project clone {id="project-clone",tag="command"}
Clone a project template from a Git repository. Calls into `git` under the hood
and can use the sparse checkout feature if available, so you're only downloading
@@ -1016,19 +1363,19 @@ what you need. By default, spaCy's
can provide any other repo (public or private) that you have access to using the
`--repo` option.
-```cli
+```bash
$ python -m spacy project clone [name] [dest] [--repo] [--branch] [--sparse]
```
> #### Example
>
-> ```cli
+> ```bash
> $ python -m spacy project clone pipelines/ner_wikiner
> ```
>
> Clone from custom repo:
>
-> ```cli
+> ```bash
> $ python -m spacy project clone template --repo https://github.com/your_org/your_repo
> ```
@@ -1042,7 +1389,7 @@ $ python -m spacy project clone [name] [dest] [--repo] [--branch] [--sparse]
| `--help`, `-h` | Show help message and available arguments. ~~bool (flag)~~ |
| **CREATES** | The cloned [project directory](/usage/projects#project-files). |
-### project assets {#project-assets tag="command"}
+### project assets {id="project-assets",tag="command"}
Fetch project assets like datasets and pretrained weights. Assets are defined in
the `assets` section of the [`project.yml`](/usage/projects#project-yml). If a
@@ -1053,13 +1400,13 @@ considered "private" and you have to take care of putting them into the
destination directory yourself. If a local path is provided, the asset is copied
into the current project.
-```cli
+```bash
$ python -m spacy project assets [project_dir]
```
> #### Example
>
-> ```cli
+> ```bash
> $ python -m spacy project assets [--sparse]
> ```
@@ -1070,7 +1417,7 @@ $ python -m spacy project assets [project_dir]
| `--help`, `-h` | Show help message and available arguments. ~~bool (flag)~~ |
| **CREATES** | Downloaded or copied assets defined in the `project.yml`. |
-### project run {#project-run tag="command"}
+### project run {id="project-run",tag="command"}
Run a named command or workflow defined in the
[`project.yml`](/usage/projects#project-yml). If a workflow name is specified,
@@ -1079,13 +1426,13 @@ all commands in the workflow are run, in order. If commands define
re-run if state has changed. For example, if the input dataset changes, a
preprocessing command that depends on those files will be re-run.
-```cli
+```bash
$ python -m spacy project run [subcommand] [project_dir] [--force] [--dry]
```
> #### Example
>
-> ```cli
+> ```bash
> $ python -m spacy project run train
> ```
@@ -1094,11 +1441,11 @@ $ python -m spacy project run [subcommand] [project_dir] [--force] [--dry]
| `subcommand` | Name of the command or workflow to run. ~~str (positional)~~ |
| `project_dir` | Path to project directory. Defaults to current working directory. ~~Path (positional)~~ |
| `--force`, `-F` | Force re-running steps, even if nothing changed. ~~bool (flag)~~ |
-| `--dry`, `-D` | Perform a dry run and don't execute scripts. ~~bool (flag)~~ |
+| `--dry`, `-D` | Perform a dry run and don't execute scripts. ~~bool (flag)~~ |
| `--help`, `-h` | Show help message and available arguments. ~~bool (flag)~~ |
| **EXECUTES** | The command defined in the `project.yml`. |
-### project push {#project-push tag="command"}
+### project push {id="project-push",tag="command"}
Upload all available files or directories listed as in the `outputs` section of
commands to a remote storage. Outputs are archived and compressed prior to
@@ -1110,20 +1457,21 @@ If the contents are different, the new version of the file is uploaded. Deleting
obsolete files is left up to you.
Remotes can be defined in the `remotes` section of the
-[`project.yml`](/usage/projects#project-yml). Under the hood, spaCy uses the
-[`smart-open`](https://github.com/RaRe-Technologies/smart_open) library to
-communicate with the remote storages, so you can use any protocol that
-`smart-open` supports, including [S3](https://aws.amazon.com/s3/),
-[Google Cloud Storage](https://cloud.google.com/storage), SSH and more, although
-you may need to install extra dependencies to use certain protocols.
+[`project.yml`](/usage/projects#project-yml). Under the hood, spaCy uses
+[`Pathy`](https://github.com/justindujardin/pathy) to communicate with the
+remote storages, so you can use any protocol that `Pathy` supports, including
+[S3](https://aws.amazon.com/s3/),
+[Google Cloud Storage](https://cloud.google.com/storage), and the local
+filesystem, although you may need to install extra dependencies to use certain
+protocols.
-```cli
+```bash
$ python -m spacy project push [remote] [project_dir]
```
> #### Example
>
-> ```cli
+> ```bash
> $ python -m spacy project push my_bucket
> ```
>
@@ -1140,7 +1488,7 @@ $ python -m spacy project push [remote] [project_dir]
| `--help`, `-h` | Show help message and available arguments. ~~bool (flag)~~ |
| **UPLOADS** | All project outputs that exist and are not already stored in the remote. |
-### project pull {#project-pull tag="command"}
+### project pull {id="project-pull",tag="command"}
Download all files or directories listed as `outputs` for commands, unless they
are not already present locally. When searching for files in the remote, `pull`
@@ -1154,20 +1502,21 @@ outputs, so if you change the config back, you'll be able to fetch back the
result.
Remotes can be defined in the `remotes` section of the
-[`project.yml`](/usage/projects#project-yml). Under the hood, spaCy uses the
-[`smart-open`](https://github.com/RaRe-Technologies/smart_open) library to
-communicate with the remote storages, so you can use any protocol that
-`smart-open` supports, including [S3](https://aws.amazon.com/s3/),
-[Google Cloud Storage](https://cloud.google.com/storage), SSH and more, although
-you may need to install extra dependencies to use certain protocols.
+[`project.yml`](/usage/projects#project-yml). Under the hood, spaCy uses
+[`Pathy`](https://github.com/justindujardin/pathy) to communicate with the
+remote storages, so you can use any protocol that `Pathy` supports, including
+[S3](https://aws.amazon.com/s3/),
+[Google Cloud Storage](https://cloud.google.com/storage), and the local
+filesystem, although you may need to install extra dependencies to use certain
+protocols.
-```cli
+```bash
$ python -m spacy project pull [remote] [project_dir]
```
> #### Example
>
-> ```cli
+> ```bash
> $ python -m spacy project pull my_bucket
> ```
>
@@ -1184,7 +1533,7 @@ $ python -m spacy project pull [remote] [project_dir]
| `--help`, `-h` | Show help message and available arguments. ~~bool (flag)~~ |
| **DOWNLOADS** | All project outputs that do not exist locally and can be found in the remote. |
-### project document {#project-document tag="command"}
+### project document {id="project-document",tag="command"}
Auto-generate a pretty Markdown-formatted `README` for your project, based on
its [`project.yml`](/usage/projects#project-yml). Will create sections that
@@ -1193,13 +1542,13 @@ content will be placed between two hidden markers, so you can add your own
custom content before or after the auto-generated documentation. When you re-run
the `project document` command, only the auto-generated part is replaced.
-```cli
+```bash
$ python -m spacy project document [project_dir] [--output] [--no-emoji]
```
> #### Example
>
-> ```cli
+> ```bash
> $ python -m spacy project document --output README.md
> ```
@@ -1208,18 +1557,18 @@ $ python -m spacy project document [project_dir] [--output] [--no-emoji]
For more examples, see the templates in our
[`projects`](https://github.com/explosion/projects) repo.
-
+
-| Name | Description |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `project_dir` | Path to project directory. Defaults to current working directory. ~~Path (positional)~~ |
-| `--output`, `-o` | Path to output file or `-` for stdout (default). If a file is specified and it already exists and contains auto-generated docs, only the auto-generated docs section is replaced. ~~Path (positional)~~ |
-| `--no-emoji`, `-NE` | Don't use emoji in the titles. ~~bool (flag)~~ |
-| **CREATES** | The Markdown-formatted project documentation. |
+| Name | Description |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `project_dir` | Path to project directory. Defaults to current working directory. ~~Path (positional)~~ |
+| `--output`, `-o` | Path to output file or `-` for stdout (default). If a file is specified and it already exists and contains auto-generated docs, only the auto-generated docs section is replaced. ~~Path (positional)~~ |
+| `--no-emoji`, `-NE` | Don't use emoji in the titles. ~~bool (flag)~~ |
+| **CREATES** | The Markdown-formatted project documentation. |
-### project dvc {#project-dvc tag="command"}
+### project dvc {id="project-dvc",tag="command"}
Auto-generate [Data Version Control](https://dvc.org) (DVC) config file. Calls
[`dvc run`](https://dvc.org/doc/command-reference/run) with `--no-exec` under
@@ -1239,13 +1588,13 @@ You'll also need to add the assets you want to track with
-```cli
-$ python -m spacy project dvc [project_dir] [workflow] [--force] [--verbose]
+```bash
+$ python -m spacy project dvc [project_dir] [workflow] [--force] [--verbose] [--quiet]
```
> #### Example
>
-> ```cli
+> ```bash
> $ git init
> $ dvc init
> $ python -m spacy project dvc all
@@ -1256,62 +1605,19 @@ $ python -m spacy project dvc [project_dir] [workflow] [--force] [--verbose]
| `project_dir` | Path to project directory. Defaults to current working directory. ~~Path (positional)~~ |
| `workflow` | Name of workflow defined in `project.yml`. Defaults to first workflow if not set. ~~Optional[str] \(option)~~ |
| `--force`, `-F` | Force-updating config file. ~~bool (flag)~~ |
-| `--verbose`, `-V` | Print more output generated by DVC. ~~bool (flag)~~ |
+| `--verbose`, `-V` | Print more output generated by DVC. ~~bool (flag)~~ |
+| `--quiet`, `-q` | Print no output generated by DVC. ~~bool (flag)~~ |
| `--help`, `-h` | Show help message and available arguments. ~~bool (flag)~~ |
| **CREATES** | A `dvc.yaml` file in the project directory, based on the steps defined in the given workflow. |
-## ray {#ray new="3"}
-
-The `spacy ray` CLI includes commands for parallel and distributed computing via
-[Ray](https://ray.io).
-
-
-
-To use this command, you need the
-[`spacy-ray`](https://github.com/explosion/spacy-ray) package installed.
-Installing the package will automatically add the `ray` command to the spaCy
-CLI.
-
-
-
-### ray train {#ray-train tag="command"}
-
-Train a spaCy pipeline using [Ray](https://ray.io) for parallel training. The
-command works just like [`spacy train`](/api/cli#train). For more details and
-examples, see the usage guide on
-[parallel training](/usage/training#parallel-training) and the spaCy project
-[integration](/usage/projects#ray).
-
-```cli
-$ python -m spacy ray train [config_path] [--code] [--output] [--n-workers] [--address] [--gpu-id] [--verbose] [overrides]
-```
-
-> #### Example
->
-> ```cli
-> $ python -m spacy ray train config.cfg --n-workers 2
-> ```
-
-| Name | Description |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `config_path` | Path to [training config](/api/data-formats#config) file containing all settings and hyperparameters. ~~Path (positional)~~ |
-| `--code`, `-c` | Path to Python file with additional code to be imported. Allows [registering custom functions](/usage/training#custom-functions) for new architectures. ~~Optional[Path] \(option)~~ |
-| `--output`, `-o` | Directory or remote storage URL for saving trained pipeline. The directory will be created if it doesn't exist. ~~Optional[Path] \(option)~~ |
-| `--n-workers`, `-n` | The number of workers. Defaults to `1`. ~~int (option)~~ |
-| `--address`, `-a` | Optional address of the Ray cluster. If not set (default), Ray will run locally. ~~Optional[str] \(option)~~ |
-| `--gpu-id`, `-g` | GPU ID or `-1` for CPU. Defaults to `-1`. ~~int (option)~~ |
-| `--verbose`, `-V` | Display more information for debugging purposes. ~~bool (flag)~~ |
-| `--help`, `-h` | Show help message and available arguments. ~~bool (flag)~~ |
-| overrides | Config parameters to override. Should be options starting with `--` that correspond to the config section and value to override, e.g. `--paths.train ./train.spacy`. ~~Any (option/flag)~~ |
-
-## huggingface-hub {#huggingface-hub new="3.1"}
+## huggingface-hub {id="huggingface-hub",version="3.1"}
The `spacy huggingface-cli` CLI includes commands for uploading your trained
spaCy pipelines to the [Hugging Face Hub](https://huggingface.co/).
> #### Installation
>
-> ```cli
+> ```bash
> $ pip install spacy-huggingface-hub
> $ huggingface-cli login
> ```
@@ -1325,19 +1631,19 @@ package installed. Installing the package will automatically add the
-### huggingface-hub push {#huggingface-hub-push tag="command"}
+### huggingface-hub push {id="huggingface-hub-push",tag="command"}
Push a spaCy pipeline to the Hugging Face Hub. Expects a `.whl` file packaged
with [`spacy package`](/api/cli#package) and `--build wheel`. For more details,
see the spaCy project [integration](/usage/projects#huggingface_hub).
-```cli
+```bash
$ python -m spacy huggingface-hub push [whl_path] [--org] [--msg] [--local-repo] [--verbose]
```
> #### Example
>
-> ```cli
+> ```bash
> $ python -m spacy huggingface-hub push en_ner_fashion-0.0.0-py3-none-any.whl
> ```
@@ -1347,5 +1653,5 @@ $ python -m spacy huggingface-hub push [whl_path] [--org] [--msg] [--local-repo]
| `--org`, `-o` | Optional name of organization to which the pipeline should be uploaded. ~~str (option)~~ |
| `--msg`, `-m` | Commit message to use for update. Defaults to `"Update spaCy pipeline"`. ~~str (option)~~ |
| `--local-repo`, `-l` | Local path to the model repository (will be created if it doesn't exist). Defaults to `hub` in the current working directory. ~~Path (option)~~ |
-| `--verbose`, `-V` | Output additional info for debugging, e.g. the full generated hub metadata. ~~bool (flag)~~ |
+| `--verbose`, `-V` | Output additional info for debugging, e.g. the full generated hub metadata. ~~bool (flag)~~ |
| **UPLOADS** | The pipeline to the hub. |
diff --git a/website/docs/api/coref.mdx b/website/docs/api/coref.mdx
new file mode 100644
index 000000000..8647f35d1
--- /dev/null
+++ b/website/docs/api/coref.mdx
@@ -0,0 +1,353 @@
+---
+title: CoreferenceResolver
+tag: class,experimental
+source: spacy-experimental/coref/coref_component.py
+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 is not yet integrated into spaCy core, and is available via the
+extension package
+[`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
+[training config](/usage/training#config) or
+`nlp.add_pipe("experimental_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
+[`SpanResolver`](/api/span-resolver) to expand single tokens to spans.
+
+## Assigned Attributes {id="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 `"coref_clusters"`, but can be passed as a
+parameter.
+
+| Location | Value |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
+| `Doc.spans[prefix + "_" + cluster_number]` | One coreference cluster, represented as single-token spans. Cluster numbers start from 1. ~~SpanGroup~~ |
+
+## Config and implementation {id="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#coref-architectures) documentation for
+details on the architectures and their arguments and hyperparameters.
+
+> #### Example
+>
+> ```python
+> 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("experimental_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~~ |
+
+## CoreferenceResolver.\_\_init\_\_ {id="init",tag="method"}
+
+> #### Example
+>
+> ```python
+> # Construction via add_pipe with default model
+> coref = nlp.add_pipe("experimental_coref")
+>
+> # Construction via add_pipe with custom model
+> config = {"model": {"@architectures": "my_coref.v1"}}
+> coref = nlp.add_pipe("experimental_coref", config=config)
+>
+> # Construction from class
+> from spacy_experimental.coref.coref_component 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\_\_ {id="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("experimental_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 {id="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("experimental_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 {id="initialize",tag="method"}
+
+Initialize the component for training. `get_examples` should be a function that
+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).
+
+> #### Example
+>
+> ```python
+> coref = nlp.add_pipe("experimental_coref")
+> coref.initialize(lambda: examples, nlp=nlp)
+> ```
+
+| 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 {id="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("experimental_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 {id="set_annotations",tag="method"}
+
+Modify a batch of documents, saving coreference clusters in `Doc.spans`.
+
+> #### Example
+>
+> ```python
+> coref = nlp.add_pipe("experimental_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 {id="update",tag="method"}
+
+Learn from a batch of [`Example`](/api/example) objects. Delegates to
+[`predict`](/api/coref#predict).
+
+> #### Example
+>
+> ```python
+> coref = nlp.add_pipe("experimental_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 {id="create_optimizer",tag="method"}
+
+Create an optimizer for the pipeline component.
+
+> #### Example
+>
+> ```python
+> coref = nlp.add_pipe("experimental_coref")
+> optimizer = coref.create_optimizer()
+> ```
+
+| Name | Description |
+| ----------- | ---------------------------- |
+| **RETURNS** | The optimizer. ~~Optimizer~~ |
+
+## CoreferenceResolver.use_params {id="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("experimental_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 {id="to_disk",tag="method"}
+
+Serialize the pipe to disk.
+
+> #### Example
+>
+> ```python
+> coref = nlp.add_pipe("experimental_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 {id="from_disk",tag="method"}
+
+Load the pipe from disk. Modifies the object in place and returns it.
+
+> #### Example
+>
+> ```python
+> coref = nlp.add_pipe("experimental_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 {id="to_bytes",tag="method"}
+
+> #### Example
+>
+> ```python
+> coref = nlp.add_pipe("experimental_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 {id="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("experimental_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 {id="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/corpus.md b/website/docs/api/corpus.mdx
similarity index 66%
rename from website/docs/api/corpus.md
rename to website/docs/api/corpus.mdx
index 35afc8fea..c58723e82 100644
--- a/website/docs/api/corpus.md
+++ b/website/docs/api/corpus.mdx
@@ -3,7 +3,7 @@ title: Corpus
teaser: An annotated corpus
tag: class
source: spacy/training/corpus.py
-new: 3
+version: 3
---
This class manages annotated corpora and can be used for training and
@@ -13,7 +13,7 @@ customize the data loading during training, you can register your own
see the usage guide on [data utilities](/usage/training#data) for more details
and examples.
-## Config and implementation {#config}
+## Config and implementation {id="config"}
`spacy.Corpus.v1` is a registered function that creates a `Corpus` of training
or evaluation data. It takes the same arguments as the `Corpus` class and
@@ -37,19 +37,19 @@ streaming.
> augmenter = null
> ```
-| Name | Description |
-| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `path` | The directory or filename to read from. Expects data in spaCy's binary [`.spacy` format](/api/data-formats#binary-training). ~~Path~~ |
-| `gold_preproc` | Whether to set up the Example object with gold-standard sentences and tokens for the predictions. See [`Corpus`](/api/corpus#init) for details. ~~bool~~ |
-| `max_length` | Maximum document length. Longer documents will be split into sentences, if sentence boundaries are available. Defaults to `0` for no limit. ~~int~~ |
-| `limit` | Limit corpus to a subset of examples, e.g. for debugging. Defaults to `0` for no limit. ~~int~~ |
-| `augmenter` | Apply some simply data augmentation, where we replace tokens with variations. This is especially useful for punctuation and case replacement, to help generalize beyond corpora that don't have smart-quotes, or only have smart quotes, etc. Defaults to `None`. ~~Optional[Callable]~~ |
+| Name | Description |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `path` | The directory or filename to read from. Expects data in spaCy's binary [`.spacy` format](/api/data-formats#binary-training). ~~Path~~ |
+| `gold_preproc` | Whether to set up the Example object with gold-standard sentences and tokens for the predictions. See [`Corpus`](/api/corpus#init) for details. ~~bool~~ |
+| `max_length` | Maximum document length. Longer documents will be split into sentences, if sentence boundaries are available. Defaults to `0` for no limit. ~~int~~ |
+| `limit` | Limit corpus to a subset of examples, e.g. for debugging. Defaults to `0` for no limit. ~~int~~ |
+| `augmenter` | Apply some simply data augmentation, where we replace tokens with variations. This is especially useful for punctuation and case replacement, to help generalize beyond corpora that don't have smart-quotes, or only have smart quotes, etc. Defaults to `None`. ~~Optional[Callable]~~ |
```python
%%GITHUB_SPACY/spacy/training/corpus.py
```
-## Corpus.\_\_init\_\_ {#init tag="method"}
+## Corpus.\_\_init\_\_ {id="init",tag="method"}
Create a `Corpus` for iterating [Example](/api/example) objects from a file or
directory of [`.spacy` data files](/api/data-formats#binary-training). The
@@ -71,17 +71,17 @@ train/test skew.
> corpus = Corpus("./data", limit=10)
> ```
-| Name | Description |
-| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `path` | The directory or filename to read from. ~~Union[str, Path]~~ |
-| _keyword-only_ | |
-| `gold_preproc` | Whether to set up the Example object with gold-standard sentences and tokens for the predictions. Defaults to `False`. ~~bool~~ |
-| `max_length` | Maximum document length. Longer documents will be split into sentences, if sentence boundaries are available. Defaults to `0` for no limit. ~~int~~ |
-| `limit` | Limit corpus to a subset of examples, e.g. for debugging. Defaults to `0` for no limit. ~~int~~ |
-| `augmenter` | Optional data augmentation callback. ~~Callable[[Language, Example], Iterable[Example]]~~ |
-| `shuffle` | Whether to shuffle the examples. Defaults to `False`. ~~bool~~ |
+| Name | Description |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `path` | The directory or filename to read from. ~~Union[str, Path]~~ |
+| _keyword-only_ | |
+| `gold_preproc` | Whether to set up the Example object with gold-standard sentences and tokens for the predictions. Defaults to `False`. ~~bool~~ |
+| `max_length` | Maximum document length. Longer documents will be split into sentences, if sentence boundaries are available. Defaults to `0` for no limit. ~~int~~ |
+| `limit` | Limit corpus to a subset of examples, e.g. for debugging. Defaults to `0` for no limit. ~~int~~ |
+| `augmenter` | Optional data augmentation callback. ~~Callable[[Language, Example], Iterable[Example]]~~ |
+| `shuffle` | Whether to shuffle the examples. Defaults to `False`. ~~bool~~ |
-## Corpus.\_\_call\_\_ {#call tag="method"}
+## Corpus.\_\_call\_\_ {id="call",tag="method"}
Yield examples from the data.
@@ -101,7 +101,7 @@ Yield examples from the data.
| `nlp` | The current `nlp` object. ~~Language~~ |
| **YIELDS** | The examples. ~~Example~~ |
-## JsonlCorpus {#jsonlcorpus tag="class"}
+## JsonlCorpus {id="jsonlcorpus",tag="class"}
Iterate Doc objects from a file or directory of JSONL (newline-delimited JSON)
formatted raw text files. Can be used to read the raw text corpus for language
@@ -120,14 +120,13 @@ file.
> srsly.write_jsonl("/path/to/text.jsonl", data)
> ```
-```json
-### Example
+```json {title="Example"}
{"text": "Can I ask where you work now and what you do, and if you enjoy it?"}
{"text": "They may just pull out of the Seattle market completely, at least until they have autonomous vehicles."}
{"text": "My cynical view on this is that it will never be free to the public. Reason: what would be the draw of joining the military? Right now their selling point is free Healthcare and Education. Ironically both are run horribly and most, that I've talked to, come out wishing they never went in."}
```
-### JsonlCorpus.\_\init\_\_ {#jsonlcorpus tag="method"}
+### JsonlCorpus.\_\_init\_\_ {id="jsonlcorpus",tag="method"}
Initialize the reader.
@@ -157,7 +156,7 @@ Initialize the reader.
| `max_length` | Maximum document length (in tokens). Longer documents will be skipped. Defaults to `0`, which indicates no limit. ~~int~~ |
| `limit` | Limit corpus to a subset of examples, e.g. for debugging. Defaults to `0` for no limit. ~~int~~ |
-### JsonlCorpus.\_\_call\_\_ {#jsonlcorpus-call tag="method"}
+### JsonlCorpus.\_\_call\_\_ {id="jsonlcorpus-call",tag="method"}
Yield examples from the data.
diff --git a/website/docs/api/cython-classes.md b/website/docs/api/cython-classes.mdx
similarity index 91%
rename from website/docs/api/cython-classes.md
rename to website/docs/api/cython-classes.mdx
index a4ecf294a..ce7c03940 100644
--- a/website/docs/api/cython-classes.md
+++ b/website/docs/api/cython-classes.mdx
@@ -9,7 +9,7 @@ menu:
- ['StringStore', 'stringstore']
---
-## Doc {#doc tag="cdef class" source="spacy/tokens/doc.pxd"}
+## Doc {id="doc",tag="cdef class",source="spacy/tokens/doc.pxd"}
The `Doc` object holds an array of [`TokenC`](/api/cython-structs#tokenc)
structs.
@@ -21,7 +21,7 @@ accessed from Python. For the Python documentation, see [`Doc`](/api/doc).
-### Attributes {#doc_attributes}
+### Attributes {id="doc_attributes"}
| Name | Description |
| ------------ | -------------------------------------------------------------------------------------------------------- |
@@ -31,7 +31,7 @@ accessed from Python. For the Python documentation, see [`Doc`](/api/doc).
| `length` | The number of tokens in the document. ~~int~~ |
| `max_length` | The underlying size of the `Doc.c` array. ~~int~~ |
-### Doc.push_back {#doc_push_back tag="method"}
+### Doc.push_back {id="doc_push_back",tag="method"}
Append a token to the `Doc`. The token can be provided as a
[`LexemeC`](/api/cython-structs#lexemec) or
@@ -55,7 +55,7 @@ Append a token to the `Doc`. The token can be provided as a
| `lex_or_tok` | The word to append to the `Doc`. ~~LexemeOrToken~~ |
| `has_space` | Whether the word has trailing whitespace. ~~bint~~ |
-## Token {#token tag="cdef class" source="spacy/tokens/token.pxd"}
+## Token {id="token",tag="cdef class",source="spacy/tokens/token.pxd"}
A Cython class providing access and methods for a
[`TokenC`](/api/cython-structs#tokenc) struct. Note that the `Token` object does
@@ -68,7 +68,7 @@ accessed from Python. For the Python documentation, see [`Token`](/api/token).
-### Attributes {#token_attributes}
+### Attributes {id="token_attributes"}
| Name | Description |
| ------- | -------------------------------------------------------------------------- |
@@ -77,7 +77,7 @@ accessed from Python. For the Python documentation, see [`Token`](/api/token).
| `i` | The offset of the token within the document. ~~int~~ |
| `doc` | The parent document. ~~Doc~~ |
-### Token.cinit {#token_cinit tag="method"}
+### Token.cinit {id="token_cinit",tag="method"}
Create a `Token` object from a `TokenC*` pointer.
@@ -94,7 +94,7 @@ Create a `Token` object from a `TokenC*` pointer.
| `offset` | The offset of the token within the document. ~~int~~ |
| `doc` | The parent document. ~~int~~ |
-## Span {#span tag="cdef class" source="spacy/tokens/span.pxd"}
+## Span {id="span",tag="cdef class",source="spacy/tokens/span.pxd"}
A Cython class providing access and methods for a slice of a `Doc` object.
@@ -105,7 +105,7 @@ accessed from Python. For the Python documentation, see [`Span`](/api/span).
-### Attributes {#span_attributes}
+### Attributes {id="span_attributes"}
| Name | Description |
| ------------ | ----------------------------------------------------------------------------- |
@@ -116,7 +116,7 @@ accessed from Python. For the Python documentation, see [`Span`](/api/span).
| `end_char` | The index of the last character of the span. ~~int~~ |
| `label` | A label to attach to the span, e.g. for named entities. ~~attr_t (uint64_t)~~ |
-## Lexeme {#lexeme tag="cdef class" source="spacy/lexeme.pxd"}
+## Lexeme {id="lexeme",tag="cdef class",source="spacy/lexeme.pxd"}
A Cython class providing access and methods for an entry in the vocabulary.
@@ -127,7 +127,7 @@ accessed from Python. For the Python documentation, see [`Lexeme`](/api/lexeme).
-### Attributes {#lexeme_attributes}
+### Attributes {id="lexeme_attributes"}
| Name | Description |
| ------- | ----------------------------------------------------------------------------- |
@@ -135,7 +135,7 @@ accessed from Python. For the Python documentation, see [`Lexeme`](/api/lexeme).
| `vocab` | A reference to the shared `Vocab` object. ~~Vocab~~ |
| `orth` | ID of the verbatim text content. ~~attr_t (uint64_t)~~ |
-## Vocab {#vocab tag="cdef class" source="spacy/vocab.pxd"}
+## Vocab {id="vocab",tag="cdef class",source="spacy/vocab.pxd"}
A Cython class providing access and methods for a vocabulary and other data
shared across a language.
@@ -147,7 +147,7 @@ accessed from Python. For the Python documentation, see [`Vocab`](/api/vocab).
-### Attributes {#vocab_attributes}
+### Attributes {id="vocab_attributes"}
| Name | Description |
| --------- | ---------------------------------------------------------------------------------------------------------- |
@@ -155,7 +155,7 @@ accessed from Python. For the Python documentation, see [`Vocab`](/api/vocab).
| `strings` | A `StringStore` that maps string to hash values and vice versa. ~~StringStore~~ |
| `length` | The number of entries in the vocabulary. ~~int~~ |
-### Vocab.get {#vocab_get tag="method"}
+### Vocab.get {id="vocab_get",tag="method"}
Retrieve a [`LexemeC*`](/api/cython-structs#lexemec) pointer from the
vocabulary.
@@ -172,7 +172,7 @@ vocabulary.
| `string` | The string of the word to look up. ~~str~~ |
| **RETURNS** | The lexeme in the vocabulary. ~~const LexemeC\*~~ |
-### Vocab.get_by_orth {#vocab_get_by_orth tag="method"}
+### Vocab.get_by_orth {id="vocab_get_by_orth",tag="method"}
Retrieve a [`LexemeC*`](/api/cython-structs#lexemec) pointer from the
vocabulary.
@@ -189,7 +189,7 @@ vocabulary.
| `orth` | ID of the verbatim text content. ~~attr_t (uint64_t)~~ |
| **RETURNS** | The lexeme in the vocabulary. ~~const LexemeC\*~~ |
-## StringStore {#stringstore tag="cdef class" source="spacy/strings.pxd"}
+## StringStore {id="stringstore",tag="cdef class",source="spacy/strings.pxd"}
A lookup table to retrieve strings by 64-bit hashes.
@@ -201,7 +201,7 @@ accessed from Python. For the Python documentation, see
-### Attributes {#stringstore_attributes}
+### Attributes {id="stringstore_attributes"}
| Name | Description |
| ------ | ---------------------------------------------------------------------------------------------------------------- |
diff --git a/website/docs/api/cython-structs.md b/website/docs/api/cython-structs.mdx
similarity index 94%
rename from website/docs/api/cython-structs.md
rename to website/docs/api/cython-structs.mdx
index 4c8514b64..106a27e90 100644
--- a/website/docs/api/cython-structs.md
+++ b/website/docs/api/cython-structs.mdx
@@ -7,7 +7,7 @@ menu:
- ['LexemeC', 'lexemec']
---
-## TokenC {#tokenc tag="C struct" source="spacy/structs.pxd"}
+## TokenC {id="tokenc",tag="C struct",source="spacy/structs.pxd"}
Cython data container for the `Token` object.
@@ -39,7 +39,7 @@ Cython data container for the `Token` object.
| `ent_type` | Named entity type. ~~attr_t (uint64_t)~~ |
| `ent_id` | ID of the entity the token is an instance of, if any. Currently not used, but potentially for coreference resolution. ~~attr_t (uint64_t)~~ |
-### Token.get_struct_attr {#token_get_struct_attr tag="staticmethod, nogil" source="spacy/tokens/token.pxd"}
+### Token.get_struct_attr {id="token_get_struct_attr",tag="staticmethod, nogil",source="spacy/tokens/token.pxd"}
Get the value of an attribute from the `TokenC` struct by attribute ID.
@@ -58,7 +58,7 @@ Get the value of an attribute from the `TokenC` struct by attribute ID.
| `feat_name` | The ID of the attribute to look up. The attributes are enumerated in `spacy.typedefs`. ~~attr_id_t~~ |
| **RETURNS** | The value of the attribute. ~~attr_t (uint64_t)~~ |
-### Token.set_struct_attr {#token_set_struct_attr tag="staticmethod, nogil" source="spacy/tokens/token.pxd"}
+### Token.set_struct_attr {id="token_set_struct_attr",tag="staticmethod, nogil",source="spacy/tokens/token.pxd"}
Set the value of an attribute of the `TokenC` struct by attribute ID.
@@ -78,7 +78,7 @@ Set the value of an attribute of the `TokenC` struct by attribute ID.
| `feat_name` | The ID of the attribute to look up. The attributes are enumerated in `spacy.typedefs`. ~~attr_id_t~~ |
| `value` | The value to set. ~~attr_t (uint64_t)~~ |
-### token_by_start {#token_by_start tag="function" source="spacy/tokens/doc.pxd"}
+### token_by_start {id="token_by_start",tag="function",source="spacy/tokens/doc.pxd"}
Find a token in a `TokenC*` array by the offset of its first character.
@@ -100,7 +100,7 @@ Find a token in a `TokenC*` array by the offset of its first character.
| `start_char` | The start index to search for. ~~int~~ |
| **RETURNS** | The index of the token in the array or `-1` if not found. ~~int~~ |
-### token_by_end {#token_by_end tag="function" source="spacy/tokens/doc.pxd"}
+### token_by_end {id="token_by_end",tag="function",source="spacy/tokens/doc.pxd"}
Find a token in a `TokenC*` array by the offset of its final character.
@@ -122,7 +122,7 @@ Find a token in a `TokenC*` array by the offset of its final character.
| `end_char` | The end index to search for. ~~int~~ |
| **RETURNS** | The index of the token in the array or `-1` if not found. ~~int~~ |
-### set_children_from_heads {#set_children_from_heads tag="function" source="spacy/tokens/doc.pxd"}
+### set_children_from_heads {id="set_children_from_heads",tag="function",source="spacy/tokens/doc.pxd"}
Set attributes that allow lookup of syntactic children on a `TokenC*` array.
This function must be called after making changes to the `TokenC.head`
@@ -148,7 +148,7 @@ attribute, in order to make the parse tree navigation consistent.
| `tokens` | A `TokenC*` array. ~~const TokenC\*~~ |
| `length` | The number of tokens in the array. ~~int~~ |
-## LexemeC {#lexemec tag="C struct" source="spacy/structs.pxd"}
+## LexemeC {id="lexemec",tag="C struct",source="spacy/structs.pxd"}
Struct holding information about a lexical type. `LexemeC` structs are usually
owned by the `Vocab`, and accessed through a read-only pointer on the `TokenC`
@@ -172,7 +172,7 @@ struct.
| `prefix` | Length-N substring from the start of the lexeme. Defaults to `N=1`. ~~attr_t (uint64_t)~~ |
| `suffix` | Length-N substring from the end of the lexeme. Defaults to `N=3`. ~~attr_t (uint64_t)~~ |
-### Lexeme.get_struct_attr {#lexeme_get_struct_attr tag="staticmethod, nogil" source="spacy/lexeme.pxd"}
+### Lexeme.get_struct_attr {id="lexeme_get_struct_attr",tag="staticmethod, nogil",source="spacy/lexeme.pxd"}
Get the value of an attribute from the `LexemeC` struct by attribute ID.
@@ -192,7 +192,7 @@ Get the value of an attribute from the `LexemeC` struct by attribute ID.
| `feat_name` | The ID of the attribute to look up. The attributes are enumerated in `spacy.typedefs`. ~~attr_id_t~~ |
| **RETURNS** | The value of the attribute. ~~attr_t (uint64_t)~~ |
-### Lexeme.set_struct_attr {#lexeme_set_struct_attr tag="staticmethod, nogil" source="spacy/lexeme.pxd"}
+### Lexeme.set_struct_attr {id="lexeme_set_struct_attr",tag="staticmethod, nogil",source="spacy/lexeme.pxd"}
Set the value of an attribute of the `LexemeC` struct by attribute ID.
@@ -212,7 +212,7 @@ Set the value of an attribute of the `LexemeC` struct by attribute ID.
| `feat_name` | The ID of the attribute to look up. The attributes are enumerated in `spacy.typedefs`. ~~attr_id_t~~ |
| `value` | The value to set. ~~attr_t (uint64_t)~~ |
-### Lexeme.c_check_flag {#lexeme_c_check_flag tag="staticmethod, nogil" source="spacy/lexeme.pxd"}
+### Lexeme.c_check_flag {id="lexeme_c_check_flag",tag="staticmethod, nogil",source="spacy/lexeme.pxd"}
Check the value of a binary flag attribute.
@@ -232,7 +232,7 @@ Check the value of a binary flag attribute.
| `flag_id` | The ID of the flag to look up. The flag IDs are enumerated in `spacy.typedefs`. ~~attr_id_t~~ |
| **RETURNS** | The boolean value of the flag. ~~bint~~ |
-### Lexeme.c_set_flag {#lexeme_c_set_flag tag="staticmethod, nogil" source="spacy/lexeme.pxd"}
+### Lexeme.c_set_flag {id="lexeme_c_set_flag",tag="staticmethod, nogil",source="spacy/lexeme.pxd"}
Set the value of a binary flag attribute.
diff --git a/website/docs/api/cython.md b/website/docs/api/cython.mdx
similarity index 99%
rename from website/docs/api/cython.md
rename to website/docs/api/cython.mdx
index 16b11cead..764ff10f4 100644
--- a/website/docs/api/cython.md
+++ b/website/docs/api/cython.mdx
@@ -6,7 +6,7 @@ menu:
- ['Conventions', 'conventions']
---
-## Overview {#overview hidden="true"}
+## Overview {id="overview",hidden="true"}
> #### What's Cython?
>
@@ -37,7 +37,7 @@ class holds a [`LexemeC`](/api/cython-structs#lexemec) struct, at `Lexeme.c`.
This lets you shed the Python container, and pass a pointer to the underlying
data into C-level functions.
-## Conventions {#conventions}
+## Conventions {id="conventions"}
spaCy's core data structures are implemented as [Cython](http://cython.org/)
`cdef` classes. Memory is managed through the
diff --git a/website/docs/api/data-formats.md b/website/docs/api/data-formats.mdx
similarity index 96%
rename from website/docs/api/data-formats.md
rename to website/docs/api/data-formats.mdx
index b7aedc511..c9d88f87c 100644
--- a/website/docs/api/data-formats.md
+++ b/website/docs/api/data-formats.mdx
@@ -14,7 +14,7 @@ vocabulary data. For an overview of label schemes used by the models, see the
[models directory](/models). Each trained pipeline documents the label schemes
used in its components, depending on the data it was trained on.
-## Training config {#config new="3"}
+## Training config {id="config",version="3"}
Config files define the training process and pipeline and can be passed to
[`spacy train`](/api/cli#train). They use
@@ -52,7 +52,7 @@ your config and check that it's valid, you can run the
-### nlp {#config-nlp tag="section"}
+### nlp {id="config-nlp",tag="section"}
> #### Example
>
@@ -83,7 +83,7 @@ Defines the `nlp` object, its tokenizer and
| `tokenizer` | The tokenizer to use. Defaults to [`Tokenizer`](/api/tokenizer). ~~Callable[[str], Doc]~~ |
| `batch_size` | Default batch size for [`Language.pipe`](/api/language#pipe) and [`Language.evaluate`](/api/language#evaluate). ~~int~~ |
-### components {#config-components tag="section"}
+### components {id="config-components",tag="section"}
> #### Example
>
@@ -106,7 +106,7 @@ function to use to create component) or a `source` (name of path of trained
pipeline to copy components from). See the docs on
[defining pipeline components](/usage/training#config-components) for details.
-### paths, system {#config-variables tag="variables"}
+### paths, system {id="config-variables",tag="variables"}
These sections define variables that can be referenced across the other sections
as variables. For example `${paths.train}` uses the value of `train` defined in
@@ -116,11 +116,11 @@ need paths, you can define them here. All config values can also be
[`spacy train`](/api/cli#train), which is especially relevant for data paths
that you don't want to hard-code in your config file.
-```cli
+```bash
$ python -m spacy train config.cfg --paths.train ./corpus/train.spacy
```
-### corpora {#config-corpora tag="section"}
+### corpora {id="config-corpora",tag="section"}
> #### Example
>
@@ -176,7 +176,7 @@ single corpus once and then divide it up into `train` and `dev` partitions.
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `corpora` | A dictionary keyed by string names, mapped to corpus functions that receive the current `nlp` object and return an iterator of [`Example`](/api/example) objects. ~~Dict[str, Callable[[Language], Iterator[Example]]]~~ |
-### training {#config-training tag="section"}
+### training {id="config-training",tag="section"}
This section defines settings and controls for the training and evaluation
process that are used when you run [`spacy train`](/api/cli#train).
@@ -186,6 +186,7 @@ process that are used when you run [`spacy train`](/api/cli#train).
| `accumulate_gradient` | Whether to divide the batch up into substeps. Defaults to `1`. ~~int~~ |
| `batcher` | Callable that takes an iterator of [`Doc`](/api/doc) objects and yields batches of `Doc`s. Defaults to [`batch_by_words`](/api/top-level#batch_by_words). ~~Callable[[Iterator[Doc], Iterator[List[Doc]]]]~~ |
| `before_to_disk` | Optional callback to modify `nlp` object right before it is saved to disk during and after training. Can be used to remove or reset config values or disable components. Defaults to `null`. ~~Optional[Callable[[Language], Language]]~~ |
+| `before_update` 3.5 | Optional callback that is invoked at the start of each training step with the `nlp` object and a `Dict` containing the following entries: `step`, `epoch`. Can be used to make deferred changes to components. Defaults to `null`. ~~Optional[Callable[[Language, Dict[str, Any]], None]]~~ |
| `dev_corpus` | Dot notation of the config location defining the dev corpus. Defaults to `corpora.dev`. ~~str~~ |
| `dropout` | The dropout rate. Defaults to `0.1`. ~~float~~ |
| `eval_frequency` | How often to evaluate during training (steps). Defaults to `200`. ~~int~~ |
@@ -201,7 +202,7 @@ process that are used when you run [`spacy train`](/api/cli#train).
| `seed` | The random seed. Defaults to variable `${system.seed}`. ~~int~~ |
| `train_corpus` | Dot notation of the config location defining the train corpus. Defaults to `corpora.train`. ~~str~~ |
-### pretraining {#config-pretraining tag="section,optional"}
+### pretraining {id="config-pretraining",tag="section,optional"}
This section is optional and defines settings and controls for
[language model pretraining](/usage/embeddings-transformers#pretraining). It's
@@ -219,7 +220,7 @@ used when you run [`spacy pretrain`](/api/cli#pretrain).
| `component` | Component name to identify the layer with the model to pretrain. Defaults to `"tok2vec"`. ~~str~~ |
| `layer` | The specific layer of the model to pretrain. If empty, the whole model will be used. ~~str~~ |
-### initialize {#config-initialize tag="section"}
+### initialize {id="config-initialize",tag="section"}
This config block lets you define resources for **initializing the pipeline**.
It's used by [`Language.initialize`](/api/language#initialize) and typically
@@ -254,9 +255,9 @@ Also see the usage guides on the
| `vectors` | Name or path of pipeline containing pretrained word vectors to use, e.g. created with [`init vectors`](/api/cli#init-vectors). Defaults to `null`. ~~Optional[str]~~ |
| `vocab_data` | Path to JSONL-formatted [vocabulary file](/api/data-formats#vocab-jsonl) to initialize vocabulary. ~~Optional[str]~~ |
-## Training data {#training}
+## Training data {id="training"}
-### Binary training format {#binary-training new="3"}
+### Binary training format {id="binary-training",version="3"}
> #### Example
>
@@ -287,7 +288,7 @@ Note that while this is the format used to save training data, you do not have
to understand the internal details to use it or create training data. See the
section on [preparing training data](/usage/training#training-data).
-### JSON training format {#json-input tag="deprecated"}
+### JSON training format {id="json-input",tag="deprecated"}
@@ -299,7 +300,7 @@ objects to JSON, you can now serialize them directly using the
[`spacy convert`](/api/cli) lets you convert your JSON data to the new `.spacy`
format:
-```cli
+```bash
$ python -m spacy convert ./data.json .
```
@@ -316,8 +317,7 @@ $ python -m spacy convert ./data.json .
> [`offsets_to_biluo_tags`](/api/top-level#offsets_to_biluo_tags) function can
> help you convert entity offsets to the right format.
-```python
-### Example structure
+```python {title="Example structure"}
[{
"id": int, # ID of the document within the corpus
"paragraphs": [{ # list of paragraphs in the corpus
@@ -356,7 +356,7 @@ https://github.com/explosion/spaCy/blob/v2.3.x/examples/training/training-data.j
-### Annotation format for creating training examples {#dict-input}
+### Annotation format for creating training examples {id="dict-input"}
An [`Example`](/api/example) object holds the information for one training
instance. It stores two [`Doc`](/api/doc) objects: one for holding the
@@ -395,12 +395,13 @@ file to keep track of your settings and hyperparameters and your own
> "pos": List[str],
> "morphs": List[str],
> "sent_starts": List[Optional[bool]],
-> "deps": List[string],
+> "deps": List[str],
> "heads": List[int],
> "entities": List[str],
> "entities": List[(int, int, str)],
> "cats": Dict[str, float],
> "links": Dict[(int, int), dict],
+> "spans": Dict[str, List[Tuple]],
> }
> ```
@@ -417,9 +418,10 @@ file to keep track of your settings and hyperparameters and your own
| `deps` | List of string values indicating the [dependency relation](/usage/linguistic-features#dependency-parse) of a token to its head. ~~List[str]~~ |
| `heads` | List of integer values indicating the dependency head of each token, referring to the absolute index of each token in the text. ~~List[int]~~ |
| `entities` | **Option 1:** List of [BILUO tags](/usage/linguistic-features#accessing-ner) per token of the format `"{action}-{label}"`, or `None` for unannotated tokens. ~~List[str]~~ |
-| `entities` | **Option 2:** List of `"(start, end, label)"` tuples defining all entities in the text. ~~List[Tuple[int, int, str]]~~ |
+| `entities` | **Option 2:** List of `(start_char, end_char, label)` tuples defining all entities in the text. ~~List[Tuple[int, int, str]]~~ |
| `cats` | Dictionary of `label`/`value` pairs indicating how relevant a certain [text category](/api/textcategorizer) is for the text. ~~Dict[str, float]~~ |
| `links` | Dictionary of `offset`/`dict` pairs defining [named entity links](/usage/linguistic-features#entity-linking). The character offsets are linked to a dictionary of relevant knowledge base IDs. ~~Dict[Tuple[int, int], Dict]~~ |
+| `spans` | Dictionary of `spans_key`/`List[Tuple]` pairs defining the spans for each spans key as `(start_char, end_char, label, kb_id)` tuples. ~~Dict[str, List[Tuple[int, int, str, str]]~~ |
@@ -433,8 +435,7 @@ file to keep track of your settings and hyperparameters and your own
-```python
-### Examples
+```python {title="Examples"}
# Training data for a part-of-speech tagger
doc = Doc(vocab, words=["I", "like", "stuff"])
gold_dict = {"tags": ["NOUN", "VERB", "NOUN"]}
@@ -463,7 +464,7 @@ gold_dict = {"entities": [(0, 12, "PERSON")],
example = Example.from_dict(doc, gold_dict)
```
-## Lexical data for vocabulary {#vocab-jsonl new="2"}
+## Lexical data for vocabulary {id="vocab-jsonl",version="2"}
This data file can be provided via the `vocab_data` setting in the
`[initialize]` block of the training config to pre-define the lexical data to
@@ -480,13 +481,11 @@ spaCy's [`Lexeme`](/api/lexeme#attributes) object.
> vocab_data = "/path/to/vocab-data.jsonl"
> ```
-```python
-### First line
+```python {title="First line"}
{"lang": "en", "settings": {"oov_prob": -20.502029418945312}}
```
-```python
-### Entry structure
+```python {title="Entry structure"}
{
"orth": string, # the word text
"id": int, # can correspond to row in vectors table
@@ -523,7 +522,7 @@ Here's an example of the 20 most frequent lexemes in the English training data:
%%GITHUB_SPACY/extra/example_data/vocab-data.jsonl
```
-## Pipeline meta {#meta}
+## Pipeline meta {id="meta"}
The pipeline meta is available as the file `meta.json` and exported
automatically when you save an `nlp` object to disk. Its contents are available
diff --git a/website/docs/api/dependencymatcher.md b/website/docs/api/dependencymatcher.mdx
similarity index 91%
rename from website/docs/api/dependencymatcher.md
rename to website/docs/api/dependencymatcher.mdx
index 356adcda7..390034a6c 100644
--- a/website/docs/api/dependencymatcher.md
+++ b/website/docs/api/dependencymatcher.mdx
@@ -2,7 +2,7 @@
title: DependencyMatcher
teaser: Match subtrees within a dependency parse
tag: class
-new: 3
+version: 3
source: spacy/matcher/dependencymatcher.pyx
---
@@ -14,7 +14,7 @@ It requires a pretrained [`DependencyParser`](/api/parser) or other component
that sets the `Token.dep` and `Token.head` attributes. See the
[usage guide](/usage/rule-based-matching#dependencymatcher) for examples.
-## Pattern format {#patterns}
+## Pattern format {id="patterns"}
> ```python
> ### Example
@@ -62,7 +62,7 @@ of relations, see the usage guide on
-### Operators
+### Operators {id="operators"}
The following operators are supported by the `DependencyMatcher`, most of which
come directly from
@@ -82,8 +82,12 @@ come directly from
| `A $- B` | `B` is a left immediate sibling of `A`, i.e. `A` and `B` have the same parent and `A.i == B.i + 1`. |
| `A $++ B` | `B` is a right sibling of `A`, i.e. `A` and `B` have the same parent and `A.i < B.i`. |
| `A $-- B` | `B` is a left sibling of `A`, i.e. `A` and `B` have the same parent and `A.i > B.i`. |
+| `A >++ B` | `B` is a right child of `A`, i.e. `A` is a parent of `B` and `A.i < B.i` _(not in Semgrex)_. |
+| `A >-- B` | `B` is a left child of `A`, i.e. `A` is a parent of `B` and `A.i > B.i` _(not in Semgrex)_. |
+| `A <++ B` | `B` is a right parent of `A`, i.e. `A` is a child of `B` and `A.i < B.i` _(not in Semgrex)_. |
+| `A <-- B` | `B` is a left parent of `A`, i.e. `A` is a child of `B` and `A.i > B.i` _(not in Semgrex)_. |
-## DependencyMatcher.\_\_init\_\_ {#init tag="method"}
+## DependencyMatcher.\_\_init\_\_ {id="init",tag="method"}
Create a `DependencyMatcher`.
@@ -100,7 +104,7 @@ Create a `DependencyMatcher`.
| _keyword-only_ | |
| `validate` | Validate all patterns added to this matcher. ~~bool~~ |
-## DependencyMatcher.\_\call\_\_ {#call tag="method"}
+## DependencyMatcher.\_\_call\_\_ {id="call",tag="method"}
Find all tokens matching the supplied patterns on the `Doc` or `Span`.
@@ -122,7 +126,7 @@ Find all tokens matching the supplied patterns on the `Doc` or `Span`.
| `doclike` | The `Doc` or `Span` to match over. ~~Union[Doc, Span]~~ |
| **RETURNS** | A list of `(match_id, token_ids)` tuples, describing the matches. The `match_id` is the ID of the match pattern and `token_ids` is a list of token indices matched by the pattern, where the position of each token in the list corresponds to the position of the node specification in the pattern. ~~List[Tuple[int, List[int]]]~~ |
-## DependencyMatcher.\_\_len\_\_ {#len tag="method"}
+## DependencyMatcher.\_\_len\_\_ {id="len",tag="method"}
Get the number of rules added to the dependency matcher. Note that this only
returns the number of rules (identical with the number of IDs), not the number
@@ -143,7 +147,7 @@ of individual patterns.
| ----------- | ---------------------------- |
| **RETURNS** | The number of rules. ~~int~~ |
-## DependencyMatcher.\_\_contains\_\_ {#contains tag="method"}
+## DependencyMatcher.\_\_contains\_\_ {id="contains",tag="method"}
Check whether the matcher contains rules for a match ID.
@@ -161,7 +165,7 @@ Check whether the matcher contains rules for a match ID.
| `key` | The match ID. ~~str~~ |
| **RETURNS** | Whether the matcher contains rules for this match ID. ~~bool~~ |
-## DependencyMatcher.add {#add tag="method"}
+## DependencyMatcher.add {id="add",tag="method"}
Add a rule to the matcher, consisting of an ID key, one or more patterns, and an
optional callback function to act on the matches. The callback function will
@@ -186,7 +190,7 @@ will be overwritten.
| _keyword-only_ | |
| `on_match` | Callback function to act on matches. Takes the arguments `matcher`, `doc`, `i` and `matches`. ~~Optional[Callable[[DependencyMatcher, Doc, int, List[Tuple], Any]]~~ |
-## DependencyMatcher.get {#get tag="method"}
+## DependencyMatcher.get {id="get",tag="method"}
Retrieve the pattern stored for a key. Returns the rule as an
`(on_match, patterns)` tuple containing the callback and available patterns.
@@ -203,7 +207,7 @@ Retrieve the pattern stored for a key. Returns the rule as an
| `key` | The ID of the match rule. ~~str~~ |
| **RETURNS** | The rule, as an `(on_match, patterns)` tuple. ~~Tuple[Optional[Callable], List[List[Union[Dict, Tuple]]]]~~ |
-## DependencyMatcher.remove {#remove tag="method"}
+## DependencyMatcher.remove {id="remove",tag="method"}
Remove a rule from the dependency matcher. A `KeyError` is raised if the match
ID does not exist.
diff --git a/website/docs/api/dependencyparser.md b/website/docs/api/dependencyparser.mdx
similarity index 93%
rename from website/docs/api/dependencyparser.md
rename to website/docs/api/dependencyparser.mdx
index 118cdc611..a6bc48cdf 100644
--- a/website/docs/api/dependencyparser.md
+++ b/website/docs/api/dependencyparser.mdx
@@ -25,7 +25,7 @@ current state. The weights are updated such that the scores assigned to the set
of optimal actions is increased, while scores assigned to other actions are
decreased. Note that more than one action may be optimal for a given state.
-## Assigned Attributes {#assigned-attributes}
+## Assigned Attributes {id="assigned-attributes"}
Dependency predictions are assigned to the `Token.dep` and `Token.head` fields.
Beside the dependencies themselves, the parser decides sentence boundaries,
@@ -39,7 +39,7 @@ which are saved in `Token.is_sent_start` and accessible via `Doc.sents`.
| `Token.is_sent_start` | A boolean value indicating whether the token starts a sentence. After the parser runs this will be `True` or `False` for all tokens. ~~bool~~ |
| `Doc.sents` | An iterator over sentences in the `Doc`, determined by `Token.is_sent_start` values. ~~Iterator[Span]~~ |
-## Config and implementation {#config}
+## Config and implementation {id="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
@@ -74,7 +74,7 @@ architectures and their arguments and hyperparameters.
%%GITHUB_SPACY/spacy/pipeline/dep_parser.pyx
```
-## DependencyParser.\_\_init\_\_ {#init tag="method"}
+## DependencyParser.\_\_init\_\_ {id="init",tag="method"}
> #### Example
>
@@ -100,14 +100,14 @@ shortcut for this and instantiate the component using its string name and
| `vocab` | The shared vocabulary. ~~Vocab~~ |
| `model` | The [`Model`](https://thinc.ai/docs/api-model) powering the pipeline component. ~~Model[List[Doc], List[Floats2d]]~~ |
| `name` | String name of the component instance. Used to add entries to the `losses` during training. ~~str~~ |
-| `moves` | A list of transition names. Inferred from the data if not provided. ~~Optional[List[str]]~~ |
+| `moves` | A list of transition names. Inferred from the data if not provided. ~~Optional[TransitionSystem]~~ |
| _keyword-only_ | |
| `update_with_oracle_cut_size` | During training, cut long sequences into shorter segments by creating intermediate states based on the gold-standard history. The model is not very sensitive to this parameter, so you usually won't need to change it. Defaults to `100`. ~~int~~ |
| `learn_tokens` | Whether to learn to merge subtokens that are split relative to the gold standard. Experimental. Defaults to `False`. ~~bool~~ |
| `min_action_freq` | The minimum frequency of labelled actions to retain. Rarer labelled actions have their label backed-off to "dep". While this primarily affects the label accuracy, it can also affect the attachment structure, as the labels are used to represent the pseudo-projectivity transformation. ~~int~~ |
| `scorer` | The scoring method. Defaults to [`Scorer.score_deps`](/api/scorer#score_deps) for the attribute `"dep"` ignoring the labels `p` and `punct` and [`Scorer.score_spans`](/api/scorer/#score_spans) for the attribute `"sents"`. ~~Optional[Callable]~~ |
-## DependencyParser.\_\_call\_\_ {#call tag="method"}
+## DependencyParser.\_\_call\_\_ {id="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
@@ -131,7 +131,7 @@ and all pipeline components are applied to the `Doc` in order. Both
| `doc` | The document to process. ~~Doc~~ |
| **RETURNS** | The processed document. ~~Doc~~ |
-## DependencyParser.pipe {#pipe tag="method"}
+## DependencyParser.pipe {id="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
@@ -155,13 +155,13 @@ applied to the `Doc` in order. Both [`__call__`](/api/dependencyparser#call) and
| `batch_size` | The number of documents to buffer. Defaults to `128`. ~~int~~ |
| **YIELDS** | The processed documents in order. ~~Doc~~ |
-## DependencyParser.initialize {#initialize tag="method" new="3"}
+## DependencyParser.initialize {id="initialize",tag="method",version="3"}
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) and lets you customize
@@ -179,7 +179,7 @@ This method was previously called `begin_training`.
>
> ```python
> parser = nlp.add_pipe("parser")
-> parser.initialize(lambda: [], nlp=nlp)
+> parser.initialize(lambda: examples, nlp=nlp)
> ```
>
> ```ini
@@ -193,12 +193,12 @@ This method was previously called `begin_training`.
| Name | Description |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `get_examples` | Function that returns gold-standard annotations in the form of [`Example`](/api/example) objects. ~~Callable[[], Iterable[Example]]~~ |
+| `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]~~ |
| `labels` | The label information to add to the component, as provided by the [`label_data`](#label_data) property after initialization. To generate a reusable JSON file from your data, you should run the [`init labels`](/api/cli#init-labels) command. If no labels are provided, the `get_examples` callback is used to extract the labels from the data, which may be a lot slower. ~~Optional[Dict[str, Dict[str, int]]]~~ |
-## DependencyParser.predict {#predict tag="method"}
+## DependencyParser.predict {id="predict",tag="method"}
Apply the component's model to a batch of [`Doc`](/api/doc) objects, without
modifying them.
@@ -215,7 +215,7 @@ modifying them.
| `docs` | The documents to predict. ~~Iterable[Doc]~~ |
| **RETURNS** | A helper class for the parse state (internal). ~~StateClass~~ |
-## DependencyParser.set_annotations {#set_annotations tag="method"}
+## DependencyParser.set_annotations {id="set_annotations",tag="method"}
Modify a batch of [`Doc`](/api/doc) objects, using pre-computed scores.
@@ -232,7 +232,7 @@ Modify a batch of [`Doc`](/api/doc) objects, using pre-computed scores.
| `docs` | The documents to modify. ~~Iterable[Doc]~~ |
| `scores` | The scores to set, produced by `DependencyParser.predict`. Returns an internal helper class for the parse state. ~~List[StateClass]~~ |
-## DependencyParser.update {#update tag="method"}
+## DependencyParser.update {id="update",tag="method"}
Learn from a batch of [`Example`](/api/example) objects, updating the pipe's
model. Delegates to [`predict`](/api/dependencyparser#predict) and
@@ -255,7 +255,7 @@ model. Delegates to [`predict`](/api/dependencyparser#predict) and
| `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]~~ |
-## DependencyParser.get_loss {#get_loss tag="method"}
+## DependencyParser.get_loss {id="get_loss",tag="method"}
Find the loss and gradient of loss for the batch of documents and their
predicted scores.
@@ -274,7 +274,7 @@ predicted scores.
| `scores` | Scores representing the model's predictions. ~~StateClass~~ |
| **RETURNS** | The loss and the gradient, i.e. `(loss, gradient)`. ~~Tuple[float, float]~~ |
-## DependencyParser.create_optimizer {#create_optimizer tag="method"}
+## DependencyParser.create_optimizer {id="create_optimizer",tag="method"}
Create an [`Optimizer`](https://thinc.ai/docs/api-optimizers) for the pipeline
component.
@@ -290,7 +290,7 @@ component.
| ----------- | ---------------------------- |
| **RETURNS** | The optimizer. ~~Optimizer~~ |
-## DependencyParser.use_params {#use_params tag="method, contextmanager"}
+## DependencyParser.use_params {id="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.
@@ -307,7 +307,7 @@ context, the original parameters are restored.
| -------- | -------------------------------------------------- |
| `params` | The parameter values to use in the model. ~~dict~~ |
-## DependencyParser.add_label {#add_label tag="method"}
+## DependencyParser.add_label {id="add_label",tag="method"}
Add a new label to the pipe. Note that you don't have to call this method if you
provide a **representative data sample** to the [`initialize`](#initialize)
@@ -327,7 +327,7 @@ to the model, and the output dimension will be
| `label` | The label to add. ~~str~~ |
| **RETURNS** | `0` if the label is already present, otherwise `1`. ~~int~~ |
-## DependencyParser.set_output {#set_output tag="method"}
+## DependencyParser.set_output {id="set_output",tag="method"}
Change the output dimension of the component's model by calling the model's
attribute `resize_output`. This is a function that takes the original model and
@@ -346,7 +346,7 @@ forgetting" problem.
| ---- | --------------------------------- |
| `nO` | The new output dimension. ~~int~~ |
-## DependencyParser.to_disk {#to_disk tag="method"}
+## DependencyParser.to_disk {id="to_disk",tag="method"}
Serialize the pipe to disk.
@@ -363,7 +363,7 @@ Serialize the pipe to disk.
| _keyword-only_ | |
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
-## DependencyParser.from_disk {#from_disk tag="method"}
+## DependencyParser.from_disk {id="from_disk",tag="method"}
Load the pipe from disk. Modifies the object in place and returns it.
@@ -381,7 +381,7 @@ Load the pipe from disk. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The modified `DependencyParser` object. ~~DependencyParser~~ |
-## DependencyParser.to_bytes {#to_bytes tag="method"}
+## DependencyParser.to_bytes {id="to_bytes",tag="method"}
> #### Example
>
@@ -398,7 +398,7 @@ Serialize the pipe to a bytestring.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The serialized form of the `DependencyParser` object. ~~bytes~~ |
-## DependencyParser.from_bytes {#from_bytes tag="method"}
+## DependencyParser.from_bytes {id="from_bytes",tag="method"}
Load the pipe from a bytestring. Modifies the object in place and returns it.
@@ -417,7 +417,7 @@ Load the pipe from a bytestring. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The `DependencyParser` object. ~~DependencyParser~~ |
-## DependencyParser.labels {#labels tag="property"}
+## DependencyParser.labels {id="labels",tag="property"}
The labels currently added to the component.
@@ -432,7 +432,7 @@ The labels currently added to the component.
| ----------- | ------------------------------------------------------ |
| **RETURNS** | The labels added to the component. ~~Tuple[str, ...]~~ |
-## DependencyParser.label_data {#label_data tag="property" new="3"}
+## DependencyParser.label_data {id="label_data",tag="property",version="3"}
The labels currently added to the component and their internal meta information.
This is the data generated by [`init labels`](/api/cli#init-labels) and used by
@@ -450,7 +450,7 @@ the model with a pre-defined label set.
| ----------- | ------------------------------------------------------------------------------- |
| **RETURNS** | The label data added to the component. ~~Dict[str, Dict[str, Dict[str, int]]]~~ |
-## Serialization fields {#serialization-fields}
+## Serialization fields {id="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
diff --git a/website/docs/api/doc.md b/website/docs/api/doc.mdx
similarity index 76%
rename from website/docs/api/doc.md
rename to website/docs/api/doc.mdx
index c21328caf..a5f3de6be 100644
--- a/website/docs/api/doc.md
+++ b/website/docs/api/doc.mdx
@@ -12,7 +12,7 @@ compressed binary strings. The `Doc` object holds an array of
[`Span`](/api/span) objects are views of this array, i.e. they don't own the
data themselves.
-## Doc.\_\_init\_\_ {#init tag="method"}
+## Doc.\_\_init\_\_ {id="init",tag="method"}
Construct a `Doc` object. The most common way to get a `Doc` object is via the
`nlp` object.
@@ -31,23 +31,23 @@ Construct a `Doc` object. The most common way to get a `Doc` object is via the
> doc = Doc(nlp.vocab, words=words, spaces=spaces)
> ```
-| Name | Description |
-| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `vocab` | A storage container for lexical types. ~~Vocab~~ |
-| `words` | A list of strings or integer hash values to add to the document as words. ~~Optional[List[Union[str,int]]]~~ |
-| `spaces` | A list of boolean values indicating whether each word has a subsequent space. Must have the same length as `words`, if specified. Defaults to a sequence of `True`. ~~Optional[List[bool]]~~ |
-| _keyword-only_ | |
-| `user\_data` | Optional extra data to attach to the Doc. ~~Dict~~ |
-| `tags` 3 | A list of strings, of the same length as `words`, to assign as `token.tag` for each word. Defaults to `None`. ~~Optional[List[str]]~~ |
-| `pos` 3 | A list of strings, of the same length as `words`, to assign as `token.pos` for each word. Defaults to `None`. ~~Optional[List[str]]~~ |
-| `morphs` 3 | A list of strings, of the same length as `words`, to assign as `token.morph` for each word. Defaults to `None`. ~~Optional[List[str]]~~ |
-| `lemmas` 3 | A list of strings, of the same length as `words`, to assign as `token.lemma` for each word. Defaults to `None`. ~~Optional[List[str]]~~ |
-| `heads` 3 | A list of values, of the same length as `words`, to assign as the head for each word. Head indices are the absolute position of the head in the `Doc`. Defaults to `None`. ~~Optional[List[int]]~~ |
-| `deps` 3 | A list of strings, of the same length as `words`, to assign as `token.dep` for each word. Defaults to `None`. ~~Optional[List[str]]~~ |
-| `sent_starts` 3 | A list of values, of the same length as `words`, to assign as `token.is_sent_start`. Will be overridden by heads if `heads` is provided. Defaults to `None`. ~~Optional[List[Optional[bool]]]~~ |
-| `ents` 3 | A list of strings, of the same length of `words`, to assign the token-based IOB tag. Defaults to `None`. ~~Optional[List[str]]~~ |
+| Name | Description |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `vocab` | A storage container for lexical types. ~~Vocab~~ |
+| `words` | A list of strings or integer hash values to add to the document as words. ~~Optional[List[Union[str,int]]]~~ |
+| `spaces` | A list of boolean values indicating whether each word has a subsequent space. Must have the same length as `words`, if specified. Defaults to a sequence of `True`. ~~Optional[List[bool]]~~ |
+| _keyword-only_ | |
+| `user\_data` | Optional extra data to attach to the Doc. ~~Dict~~ |
+| `tags` 3 | A list of strings, of the same length as `words`, to assign as `token.tag` for each word. Defaults to `None`. ~~Optional[List[str]]~~ |
+| `pos` 3 | A list of strings, of the same length as `words`, to assign as `token.pos` for each word. Defaults to `None`. ~~Optional[List[str]]~~ |
+| `morphs` 3 | A list of strings, of the same length as `words`, to assign as `token.morph` for each word. Defaults to `None`. ~~Optional[List[str]]~~ |
+| `lemmas` 3 | A list of strings, of the same length as `words`, to assign as `token.lemma` for each word. Defaults to `None`. ~~Optional[List[str]]~~ |
+| `heads` 3 | A list of values, of the same length as `words`, to assign as the head for each word. Head indices are the absolute position of the head in the `Doc`. Defaults to `None`. ~~Optional[List[int]]~~ |
+| `deps` 3 | A list of strings, of the same length as `words`, to assign as `token.dep` for each word. Defaults to `None`. ~~Optional[List[str]]~~ |
+| `sent_starts` 3 | A list of values, of the same length as `words`, to assign as `token.is_sent_start`. Will be overridden by heads if `heads` is provided. Defaults to `None`. ~~Optional[List[Union[bool, int, None]]]~~ |
+| `ents` 3 | A list of strings, of the same length of `words`, to assign the token-based IOB tag. Defaults to `None`. ~~Optional[List[str]]~~ |
-## Doc.\_\_getitem\_\_ {#getitem tag="method"}
+## Doc.\_\_getitem\_\_ {id="getitem",tag="method"}
Get a [`Token`](/api/token) object at position `i`, where `i` is an integer.
Negative indexing is supported, and follows the usual Python semantics, i.e.
@@ -80,7 +80,7 @@ semantics.
| `start_end` | The slice of the document to get. ~~Tuple[int, int]~~ |
| **RETURNS** | The span at `doc[start:end]`. ~~Span~~ |
-## Doc.\_\_iter\_\_ {#iter tag="method"}
+## Doc.\_\_iter\_\_ {id="iter",tag="method"}
Iterate over `Token` objects, from which the annotations can be easily accessed.
@@ -100,7 +100,7 @@ underlying C data directly from Cython.
| ---------- | --------------------------- |
| **YIELDS** | A `Token` object. ~~Token~~ |
-## Doc.\_\_len\_\_ {#len tag="method"}
+## Doc.\_\_len\_\_ {id="len",tag="method"}
Get the number of tokens in the document.
@@ -115,7 +115,7 @@ Get the number of tokens in the document.
| ----------- | --------------------------------------------- |
| **RETURNS** | The number of tokens in the document. ~~int~~ |
-## Doc.set_extension {#set_extension tag="classmethod" new="2"}
+## Doc.set_extension {id="set_extension",tag="classmethod",version="2"}
Define a custom attribute on the `Doc` which becomes available via `Doc._`. For
details, see the documentation on
@@ -140,7 +140,7 @@ details, see the documentation on
| `setter` | Setter function that takes the `Doc` and a value, and modifies the object. Is called when the user writes to the `Doc._` attribute. ~~Optional[Callable[[Doc, Any], None]]~~ |
| `force` | Force overwriting existing attribute. ~~bool~~ |
-## Doc.get_extension {#get_extension tag="classmethod" new="2"}
+## Doc.get_extension {id="get_extension",tag="classmethod",version="2"}
Look up a previously registered extension by name. Returns a 4-tuple
`(default, method, getter, setter)` if the extension is registered. Raises a
@@ -160,7 +160,7 @@ Look up a previously registered extension by name. Returns a 4-tuple
| `name` | Name of the extension. ~~str~~ |
| **RETURNS** | A `(default, method, getter, setter)` tuple of the extension. ~~Tuple[Optional[Any], Optional[Callable], Optional[Callable], Optional[Callable]]~~ |
-## Doc.has_extension {#has_extension tag="classmethod" new="2"}
+## Doc.has_extension {id="has_extension",tag="classmethod",version="2"}
Check whether an extension has been registered on the `Doc` class.
@@ -177,7 +177,7 @@ Check whether an extension has been registered on the `Doc` class.
| `name` | Name of the extension to check. ~~str~~ |
| **RETURNS** | Whether the extension has been registered. ~~bool~~ |
-## Doc.remove_extension {#remove_extension tag="classmethod" new="2.0.12"}
+## Doc.remove_extension {id="remove_extension",tag="classmethod",version="2.0.12"}
Remove a previously registered extension.
@@ -195,7 +195,7 @@ Remove a previously registered extension.
| `name` | Name of the extension. ~~str~~ |
| **RETURNS** | A `(default, method, getter, setter)` tuple of the removed extension. ~~Tuple[Optional[Any], Optional[Callable], Optional[Callable], Optional[Callable]]~~ |
-## Doc.char_span {#char_span tag="method" new="2"}
+## Doc.char_span {id="char_span",tag="method",version="2"}
Create a `Span` object from the slice `doc.text[start_idx:end_idx]`. Returns
`None` if the character indices don't map to a valid span using the default
@@ -209,17 +209,17 @@ alignment mode `"strict".
> assert span.text == "New York"
> ```
-| Name | Description |
-| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `start` | The index of the first character of the span. ~~int~~ |
-| `end` | The index of the last character after the span. ~~int~~ |
-| `label` | A label to attach to the span, e.g. for named entities. ~~Union[int, str]~~ |
-| `kb_id` 2.2 | An ID from a knowledge base to capture the meaning of a named entity. ~~Union[int, str]~~ |
-| `vector` | A meaning representation of the span. ~~numpy.ndarray[ndim=1, dtype=float32]~~ |
-| `alignment_mode` | How character indices snap to token boundaries. Options: `"strict"` (no snapping), `"contract"` (span of all tokens completely within the character span), `"expand"` (span of all tokens at least partially covered by the character span). Defaults to `"strict"`. ~~str~~ |
-| **RETURNS** | The newly constructed object or `None`. ~~Optional[Span]~~ |
+| Name | Description |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `start` | The index of the first character of the span. ~~int~~ |
+| `end` | The index of the last character after the span. ~~int~~ |
+| `label` | A label to attach to the span, e.g. for named entities. ~~Union[int, str]~~ |
+| `kb_id` | An ID from a knowledge base to capture the meaning of a named entity. ~~Union[int, str]~~ |
+| `vector` | A meaning representation of the span. ~~numpy.ndarray[ndim=1, dtype=float32]~~ |
+| `alignment_mode` | How character indices snap to token boundaries. Options: `"strict"` (no snapping), `"contract"` (span of all tokens completely within the character span), `"expand"` (span of all tokens at least partially covered by the character span). Defaults to `"strict"`. ~~str~~ |
+| **RETURNS** | The newly constructed object or `None`. ~~Optional[Span]~~ |
-## Doc.set_ents {#set_ents tag="method" new="3"}
+## Doc.set_ents {id="set_ents",tag="method",version="3"}
Set the named entities in the document.
@@ -243,7 +243,7 @@ Set the named entities in the document.
| `outside` | Spans outside of entities (O in IOB). ~~Optional[List[Span]]~~ |
| `default` | How to set entity annotation for tokens outside of any provided spans. Options: `"blocked"`, `"missing"`, `"outside"` and `"unmodified"` (preserve current state). Defaults to `"outside"`. ~~str~~ |
-## Doc.similarity {#similarity tag="method" model="vectors"}
+## Doc.similarity {id="similarity",tag="method",model="vectors"}
Make a semantic similarity estimate. The default estimate is cosine similarity
using an average of word vectors.
@@ -263,7 +263,7 @@ using an average of word vectors.
| `other` | The object to compare with. By default, accepts `Doc`, `Span`, `Token` and `Lexeme` objects. ~~Union[Doc, Span, Token, Lexeme]~~ |
| **RETURNS** | A scalar similarity score. Higher is more similar. ~~float~~ |
-## Doc.count_by {#count_by tag="method"}
+## Doc.count_by {id="count_by",tag="method"}
Count the frequencies of a given attribute. Produces a dict of
`{attr (int): count (ints)}` frequencies, keyed by the values of the given
@@ -284,7 +284,7 @@ attribute ID.
| `attr_id` | The attribute ID. ~~int~~ |
| **RETURNS** | A dictionary mapping attributes to integer counts. ~~Dict[int, int]~~ |
-## Doc.get_lca_matrix {#get_lca_matrix tag="method"}
+## Doc.get_lca_matrix {id="get_lca_matrix",tag="method"}
Calculates the lowest common ancestor matrix for a given `Doc`. Returns LCA
matrix containing the integer index of the ancestor, or `-1` if no common
@@ -302,9 +302,10 @@ ancestor is found, e.g. if span excludes a necessary ancestor.
| ----------- | -------------------------------------------------------------------------------------- |
| **RETURNS** | The lowest common ancestor matrix of the `Doc`. ~~numpy.ndarray[ndim=2, dtype=int32]~~ |
-## Doc.has_annotation {#has_annotation tag="method"}
+## Doc.has_annotation {id="has_annotation",tag="method"}
-Check whether the doc contains annotation on a [`Token` attribute](/api/token#attributes).
+Check whether the doc contains annotation on a
+[`Token` attribute](/api/token#attributes).
@@ -326,7 +327,7 @@ doc = nlp("This is a text")
| `require_complete` | Whether to check that the attribute is set on every token in the doc. Defaults to `False`. ~~bool~~ |
| **RETURNS** | Whether specified annotation is present in the doc. ~~bool~~ |
-## Doc.to_array {#to_array tag="method"}
+## Doc.to_array {id="to_array",tag="method"}
Export given token attributes to a numpy `ndarray`. If `attr_ids` is a sequence
of `M` attributes, the output array will be of shape `(N, M)`, where `N` is the
@@ -354,7 +355,7 @@ Returns a 2D array with one row per token and one column per attribute (when
| `attr_ids` | A list of attributes (int IDs or string names) or a single attribute (int ID or string name). ~~Union[int, str, List[Union[int, str]]]~~ |
| **RETURNS** | The exported attributes as a numpy array. ~~Union[numpy.ndarray[ndim=2, dtype=uint64], numpy.ndarray[ndim=1, dtype=uint64]]~~ |
-## Doc.from_array {#from_array tag="method"}
+## Doc.from_array {id="from_array",tag="method"}
Load attributes from a numpy array. Write to a `Doc` object, from an `(M, N)`
array of attributes.
@@ -378,7 +379,7 @@ array of attributes.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The `Doc` itself. ~~Doc~~ |
-## Doc.from_docs {#from_docs tag="staticmethod" new="3"}
+## Doc.from_docs {id="from_docs",tag="staticmethod",version="3"}
Concatenate multiple `Doc` objects to form a new one. Raises an error if the
`Doc` objects do not all share the same `Vocab`.
@@ -398,14 +399,16 @@ Concatenate multiple `Doc` objects to form a new one. Raises an error if the
> [str(ent) for doc in docs for ent in doc.ents]
> ```
-| Name | Description |
-| ------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `docs` | A list of `Doc` objects. ~~List[Doc]~~ |
-| `ensure_whitespace` | Insert a space between two adjacent docs whenever the first doc does not end in whitespace. ~~bool~~ |
-| `attrs` | Optional list of attribute ID ints or attribute name strings. ~~Optional[List[Union[str, int]]]~~ |
-| **RETURNS** | The new `Doc` object that is containing the other docs or `None`, if `docs` is empty or `None`. ~~Optional[Doc]~~ |
+| Name | Description |
+| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `docs` | A list of `Doc` objects. ~~List[Doc]~~ |
+| `ensure_whitespace` | Insert a space between two adjacent docs whenever the first doc does not end in whitespace. ~~bool~~ |
+| `attrs` | Optional list of attribute ID ints or attribute name strings. ~~Optional[List[Union[str, int]]]~~ |
+| _keyword-only_ | |
+| `exclude` 3.3 | String names of Doc attributes to exclude. Supported: `spans`, `tensor`, `user_data`. ~~Iterable[str]~~ |
+| **RETURNS** | The new `Doc` object that is containing the other docs or `None`, if `docs` is empty or `None`. ~~Optional[Doc]~~ |
-## Doc.to_disk {#to_disk tag="method" new="2"}
+## Doc.to_disk {id="to_disk",tag="method",version="2"}
Save the current state to a directory.
@@ -421,7 +424,7 @@ Save the current state to a directory.
| _keyword-only_ | |
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
-## Doc.from_disk {#from_disk tag="method" new="2"}
+## Doc.from_disk {id="from_disk",tag="method",version="2"}
Loads state from a directory. Modifies the object in place and returns it.
@@ -440,7 +443,7 @@ Loads state from a directory. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The modified `Doc` object. ~~Doc~~ |
-## Doc.to_bytes {#to_bytes tag="method"}
+## Doc.to_bytes {id="to_bytes",tag="method"}
Serialize, i.e. export the document contents to a binary string.
@@ -457,7 +460,7 @@ Serialize, i.e. export the document contents to a binary string.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | A losslessly serialized copy of the `Doc`, including all annotations. ~~bytes~~ |
-## Doc.from_bytes {#from_bytes tag="method"}
+## Doc.from_bytes {id="from_bytes",tag="method"}
Deserialize, i.e. import the document contents from a binary string.
@@ -478,7 +481,46 @@ Deserialize, i.e. import the document contents from a binary string.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The `Doc` object. ~~Doc~~ |
-## Doc.retokenize {#retokenize tag="contextmanager" new="2.1"}
+## Doc.to_json {id="to_json",tag="method"}
+
+Serializes a document to JSON. Note that this is format differs from the
+deprecated [`JSON training format`](/api/data-formats#json-input).
+
+> #### Example
+>
+> ```python
+> doc = nlp("All we have to decide is what to do with the time that is given us.")
+> assert doc.to_json()["text"] == doc.text
+> ```
+
+| Name | Description |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `underscore` | Optional list of string names of custom `Doc` attributes. Attribute values need to be JSON-serializable. Values will be added to an `"_"` key in the data, e.g. `"_": {"foo": "bar"}`. ~~Optional[List[str]]~~ |
+| **RETURNS** | The data in JSON format. ~~Dict[str, Any]~~ |
+
+## Doc.from_json {id="from_json",tag="method",version="3.3.1"}
+
+Deserializes a document from JSON, i.e. generates a document from the provided
+JSON data as generated by [`Doc.to_json()`](/api/doc#to_json).
+
+> #### Example
+>
+> ```python
+> from spacy.tokens import Doc
+> doc = nlp("All we have to decide is what to do with the time that is given us.")
+> doc_json = doc.to_json()
+> deserialized_doc = Doc(nlp.vocab).from_json(doc_json)
+> assert deserialized_doc.text == doc.text == doc_json["text"]
+> ```
+
+| Name | Description |
+| -------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `doc_json` | The Doc data in JSON format from [`Doc.to_json`](#to_json). ~~Dict[str, Any]~~ |
+| _keyword-only_ | |
+| `validate` | Whether to validate the JSON input against the expected schema for detailed debugging. Defaults to `False`. ~~bool~~ |
+| **RETURNS** | A `Doc` corresponding to the provided JSON. ~~Doc~~ |
+
+## Doc.retokenize {id="retokenize",tag="contextmanager",version="2.1"}
Context manager to handle retokenization of the `Doc`. Modifications to the
`Doc`'s tokenization are stored, and then made all at once when the context
@@ -498,7 +540,7 @@ invalidated, although they may accidentally continue to work.
| ----------- | -------------------------------- |
| **RETURNS** | The retokenizer. ~~Retokenizer~~ |
-### Retokenizer.merge {#retokenizer.merge tag="method"}
+### Retokenizer.merge {id="retokenizer.merge",tag="method"}
Mark a span for merging. The `attrs` will be applied to the resulting token (if
they're context-dependent token attributes like `LEMMA` or `DEP`) or to the
@@ -521,7 +563,7 @@ values.
| `span` | The span to merge. ~~Span~~ |
| `attrs` | Attributes to set on the merged token. ~~Dict[Union[str, int], Any]~~ |
-### Retokenizer.split {#retokenizer.split tag="method"}
+### Retokenizer.split {id="retokenizer.split",tag="method"}
Mark a token for splitting, into the specified `orths`. The `heads` are required
to specify how the new subtokens should be integrated into the dependency tree.
@@ -557,7 +599,7 @@ underlying lexeme (if they're context-independent lexical attributes like
| `heads` | List of `token` or `(token, subtoken)` tuples specifying the tokens to attach the newly split subtokens to. ~~List[Union[Token, Tuple[Token, int]]]~~ |
| `attrs` | Attributes to set on all split tokens. Attribute names mapped to list of per-token attribute values. ~~Dict[Union[str, int], List[Any]]~~ |
-## Doc.ents {#ents tag="property" model="NER"}
+## Doc.ents {id="ents",tag="property",model="NER"}
The named entities in the document. Returns a tuple of named entity `Span`
objects, if the entity recognizer has been applied.
@@ -575,7 +617,7 @@ objects, if the entity recognizer has been applied.
| ----------- | ---------------------------------------------------------------- |
| **RETURNS** | Entities in the document, one `Span` per entity. ~~Tuple[Span]~~ |
-## Doc.spans {#spans tag="property"}
+## Doc.spans {id="spans",tag="property"}
A dictionary of named span groups, to store and access additional span
annotations. You can write to it by assigning a list of [`Span`](/api/span)
@@ -585,14 +627,14 @@ objects or a [`SpanGroup`](/api/spangroup) to a given key.
>
> ```python
> doc = nlp("Their goi ng home")
-> doc.spans["errors"] = [doc[0:1], doc[2:4]]
+> doc.spans["errors"] = [doc[0:1], doc[1:3]]
> ```
| Name | Description |
| ----------- | ------------------------------------------------------------------ |
| **RETURNS** | The span groups assigned to the document. ~~Dict[str, SpanGroup]~~ |
-## Doc.cats {#cats tag="property" model="text classifier"}
+## Doc.cats {id="cats",tag="property",model="text classifier"}
Maps a label to a score for categories applied to the document. Typically set by
the [`TextCategorizer`](/api/textcategorizer).
@@ -608,7 +650,7 @@ the [`TextCategorizer`](/api/textcategorizer).
| ----------- | ---------------------------------------------------------- |
| **RETURNS** | The text categories mapped to scores. ~~Dict[str, float]~~ |
-## Doc.noun_chunks {#noun_chunks tag="property" model="parser"}
+## Doc.noun_chunks {id="noun_chunks",tag="property",model="parser"}
Iterate over the base noun phrases in the document. Yields base noun-phrase
`Span` objects, if the document has been syntactically parsed. A base noun
@@ -618,7 +660,7 @@ relative clauses.
To customize the noun chunk iterator in a loaded pipeline, modify
[`nlp.vocab.get_noun_chunks`](/api/vocab#attributes). If the `noun_chunk`
-[syntax iterator](/usage/adding-languages#language-data) has not been
+[syntax iterator](/usage/linguistic-features#language-data) has not been
implemented for the given language, a `NotImplementedError` is raised.
> #### Example
@@ -635,7 +677,7 @@ implemented for the given language, a `NotImplementedError` is raised.
| ---------- | ------------------------------------- |
| **YIELDS** | Noun chunks in the document. ~~Span~~ |
-## Doc.sents {#sents tag="property" model="sentences"}
+## Doc.sents {id="sents",tag="property",model="sentences"}
Iterate over the sentences in the document. Sentence spans have no label.
@@ -657,7 +699,7 @@ will raise an error otherwise.
| ---------- | ----------------------------------- |
| **YIELDS** | Sentences in the document. ~~Span~~ |
-## Doc.has_vector {#has_vector tag="property" model="vectors"}
+## Doc.has_vector {id="has_vector",tag="property",model="vectors"}
A boolean value indicating whether a word vector is associated with the object.
@@ -672,7 +714,7 @@ A boolean value indicating whether a word vector is associated with the object.
| ----------- | --------------------------------------------------------- |
| **RETURNS** | Whether the document has a vector data attached. ~~bool~~ |
-## Doc.vector {#vector tag="property" model="vectors"}
+## Doc.vector {id="vector",tag="property",model="vectors"}
A real-valued meaning representation. Defaults to an average of the token
vectors.
@@ -689,7 +731,7 @@ vectors.
| ----------- | -------------------------------------------------------------------------------------------------- |
| **RETURNS** | A 1-dimensional array representing the document's vector. ~~numpy.ndarray[ndim=1, dtype=float32]~~ |
-## Doc.vector_norm {#vector_norm tag="property" model="vectors"}
+## Doc.vector_norm {id="vector_norm",tag="property",model="vectors"}
The L2 norm of the document's vector representation.
@@ -707,26 +749,26 @@ The L2 norm of the document's vector representation.
| ----------- | --------------------------------------------------- |
| **RETURNS** | The L2 norm of the vector representation. ~~float~~ |
-## Attributes {#attributes}
+## Attributes {id="attributes"}
-| Name | Description |
-| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `text` | A string representation of the document text. ~~str~~ |
-| `text_with_ws` | An alias of `Doc.text`, provided for duck-type compatibility with `Span` and `Token`. ~~str~~ |
-| `mem` | The document's local memory heap, for all C data it owns. ~~cymem.Pool~~ |
-| `vocab` | The store of lexical types. ~~Vocab~~ |
-| `tensor` 2 | Container for dense vector representations. ~~numpy.ndarray~~ |
-| `user_data` | A generic storage area, for user custom data. ~~Dict[str, Any]~~ |
-| `lang` 2.1 | Language of the document's vocabulary. ~~int~~ |
-| `lang_` 2.1 | Language of the document's vocabulary. ~~str~~ |
-| `sentiment` | The document's positivity/negativity score, if available. ~~float~~ |
-| `user_hooks` | A dictionary that allows customization of the `Doc`'s properties. ~~Dict[str, Callable]~~ |
-| `user_token_hooks` | A dictionary that allows customization of properties of `Token` children. ~~Dict[str, Callable]~~ |
-| `user_span_hooks` | A dictionary that allows customization of properties of `Span` children. ~~Dict[str, Callable]~~ |
-| `has_unknown_spaces` | Whether the document was constructed without known spacing between tokens (typically when created from gold tokenization). ~~bool~~ |
-| `_` | User space for adding custom [attribute extensions](/usage/processing-pipelines#custom-components-attributes). ~~Underscore~~ |
+| Name | Description |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `text` | A string representation of the document text. ~~str~~ |
+| `text_with_ws` | An alias of `Doc.text`, provided for duck-type compatibility with `Span` and `Token`. ~~str~~ |
+| `mem` | The document's local memory heap, for all C data it owns. ~~cymem.Pool~~ |
+| `vocab` | The store of lexical types. ~~Vocab~~ |
+| `tensor` | Container for dense vector representations. ~~numpy.ndarray~~ |
+| `user_data` | A generic storage area, for user custom data. ~~Dict[str, Any]~~ |
+| `lang` | Language of the document's vocabulary. ~~int~~ |
+| `lang_` | Language of the document's vocabulary. ~~str~~ |
+| `sentiment` | The document's positivity/negativity score, if available. ~~float~~ |
+| `user_hooks` | A dictionary that allows customization of the `Doc`'s properties. ~~Dict[str, Callable]~~ |
+| `user_token_hooks` | A dictionary that allows customization of properties of `Token` children. ~~Dict[str, Callable]~~ |
+| `user_span_hooks` | A dictionary that allows customization of properties of `Span` children. ~~Dict[str, Callable]~~ |
+| `has_unknown_spaces` | Whether the document was constructed without known spacing between tokens (typically when created from gold tokenization). ~~bool~~ |
+| `_` | User space for adding custom [attribute extensions](/usage/processing-pipelines#custom-components-attributes). ~~Underscore~~ |
-## Serialization fields {#serialization-fields}
+## Serialization fields {id="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
diff --git a/website/docs/api/docbin.md b/website/docs/api/docbin.mdx
similarity index 93%
rename from website/docs/api/docbin.md
rename to website/docs/api/docbin.mdx
index b1d1798ba..b5cf29df7 100644
--- a/website/docs/api/docbin.md
+++ b/website/docs/api/docbin.mdx
@@ -1,7 +1,7 @@
---
title: DocBin
tag: class
-new: 2.2
+version: 2.2
teaser: Pack Doc objects for binary serialization
source: spacy/tokens/_serialize.py
---
@@ -15,8 +15,7 @@ notable downside to this format is that you can't easily extract just one
document from the `DocBin`. The serialization format is gzipped msgpack, where
the msgpack object has the following structure:
-```python
-### msgpack object structure
+```python {title="msgpack object structure"}
{
"version": str, # DocBin version number
"attrs": List[uint64], # e.g. [TAG, HEAD, ENT_IOB, ENT_TYPE]
@@ -33,7 +32,7 @@ object. This means the storage is more efficient if you pack more documents
together, because you have less duplication in the strings. For usage examples,
see the docs on [serializing `Doc` objects](/usage/saving-loading#docs).
-## DocBin.\_\_init\_\_ {#init tag="method"}
+## DocBin.\_\_init\_\_ {id="init",tag="method"}
Create a `DocBin` object to hold serialized annotations.
@@ -50,7 +49,7 @@ Create a `DocBin` object to hold serialized annotations.
| `store_user_data` | Whether to write the `Doc.user_data` and the values of custom extension attributes to file/bytes. Defaults to `False`. ~~bool~~ |
| `docs` | `Doc` objects to add on initialization. ~~Iterable[Doc]~~ |
-## DocBin.\_\len\_\_ {#len tag="method"}
+## DocBin.\_\_len\_\_ {id="len",tag="method"}
Get the number of `Doc` objects that were added to the `DocBin`.
@@ -67,7 +66,7 @@ Get the number of `Doc` objects that were added to the `DocBin`.
| ----------- | --------------------------------------------------- |
| **RETURNS** | The number of `Doc`s added to the `DocBin`. ~~int~~ |
-## DocBin.add {#add tag="method"}
+## DocBin.add {id="add",tag="method"}
Add a `Doc`'s annotations to the `DocBin` for serialization.
@@ -83,7 +82,7 @@ Add a `Doc`'s annotations to the `DocBin` for serialization.
| -------- | -------------------------------- |
| `doc` | The `Doc` object to add. ~~Doc~~ |
-## DocBin.get_docs {#get_docs tag="method"}
+## DocBin.get_docs {id="get_docs",tag="method"}
Recover `Doc` objects from the annotations, using the given vocab.
@@ -98,7 +97,7 @@ Recover `Doc` objects from the annotations, using the given vocab.
| `vocab` | The shared vocab. ~~Vocab~~ |
| **YIELDS** | The `Doc` objects. ~~Doc~~ |
-## DocBin.merge {#merge tag="method"}
+## DocBin.merge {id="merge",tag="method"}
Extend the annotations of this `DocBin` with the annotations from another. Will
raise an error if the pre-defined `attrs` of the two `DocBin`s don't match.
@@ -118,7 +117,7 @@ raise an error if the pre-defined `attrs` of the two `DocBin`s don't match.
| -------- | ------------------------------------------------------ |
| `other` | The `DocBin` to merge into the current bin. ~~DocBin~~ |
-## DocBin.to_bytes {#to_bytes tag="method"}
+## DocBin.to_bytes {id="to_bytes",tag="method"}
Serialize the `DocBin`'s annotations to a bytestring.
@@ -134,7 +133,7 @@ Serialize the `DocBin`'s annotations to a bytestring.
| ----------- | ---------------------------------- |
| **RETURNS** | The serialized `DocBin`. ~~bytes~~ |
-## DocBin.from_bytes {#from_bytes tag="method"}
+## DocBin.from_bytes {id="from_bytes",tag="method"}
Deserialize the `DocBin`'s annotations from a bytestring.
@@ -150,7 +149,7 @@ Deserialize the `DocBin`'s annotations from a bytestring.
| `bytes_data` | The data to load from. ~~bytes~~ |
| **RETURNS** | The loaded `DocBin`. ~~DocBin~~ |
-## DocBin.to_disk {#to_disk tag="method" new="3"}
+## DocBin.to_disk {id="to_disk",tag="method",version="3"}
Save the serialized `DocBin` to a file. Typically uses the `.spacy` extension
and the result can be used as the input data for
@@ -168,7 +167,7 @@ and the result can be used as the input data for
| -------- | -------------------------------------------------------------------------- |
| `path` | The file path, typically with the `.spacy` extension. ~~Union[str, Path]~~ |
-## DocBin.from_disk {#from_disk tag="method" new="3"}
+## DocBin.from_disk {id="from_disk",tag="method",version="3"}
Load a serialized `DocBin` from a file. Typically uses the `.spacy` extension.
diff --git a/website/docs/api/edittreelemmatizer.mdx b/website/docs/api/edittreelemmatizer.mdx
new file mode 100644
index 000000000..82967482c
--- /dev/null
+++ b/website/docs/api/edittreelemmatizer.mdx
@@ -0,0 +1,409 @@
+---
+title: EditTreeLemmatizer
+tag: class
+source: spacy/pipeline/edit_tree_lemmatizer.py
+version: 3.3
+teaser: 'Pipeline component for lemmatization'
+api_base_class: /api/pipe
+api_string_name: trainable_lemmatizer
+api_trainable: true
+---
+
+A trainable component for assigning base forms to tokens. This lemmatizer uses
+**edit trees** to transform tokens into base forms. The lemmatization model
+predicts which edit tree is applicable to a token. The edit tree data structure
+and construction method used by this lemmatizer were proposed in
+[Joint Lemmatization and Morphological Tagging with Lemming](https://aclanthology.org/D15-1272.pdf)
+(Thomas Müller et al., 2015).
+
+For a lookup and rule-based lemmatizer, see [`Lemmatizer`](/api/lemmatizer).
+
+## Assigned Attributes {id="assigned-attributes"}
+
+Predictions are assigned to `Token.lemma`.
+
+| Location | Value |
+| -------------- | ------------------------- |
+| `Token.lemma` | The lemma (hash). ~~int~~ |
+| `Token.lemma_` | The lemma. ~~str~~ |
+
+## Config and implementation {id="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.edit_tree_lemmatizer import DEFAULT_EDIT_TREE_LEMMATIZER_MODEL
+> config = {"model": DEFAULT_EDIT_TREE_LEMMATIZER_MODEL}
+> nlp.add_pipe("trainable_lemmatizer", config=config, name="lemmatizer")
+> ```
+
+| Setting | Description |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `model` | A model instance that predicts the edit tree probabilities. The output vectors should match the number of edit trees in size, and be normalized as probabilities (all scores between 0 and 1, with the rows summing to `1`). Defaults to [Tagger](/api/architectures#Tagger). ~~Model[List[Doc], List[Floats2d]]~~ |
+| `backoff` | ~~Token~~ attribute to use when no applicable edit tree is found. Defaults to `orth`. ~~str~~ |
+| `min_tree_freq` | Minimum frequency of an edit tree in the training set to be used. Defaults to `3`. ~~int~~ |
+| `overwrite` | Whether existing annotation is overwritten. Defaults to `False`. ~~bool~~ |
+| `top_k` | The number of most probable edit trees to try before resorting to `backoff`. Defaults to `1`. ~~int~~ |
+| `scorer` | The scoring method. Defaults to [`Scorer.score_token_attr`](/api/scorer#score_token_attr) for the attribute `"lemma"`. ~~Optional[Callable]~~ |
+
+```python
+%%GITHUB_SPACY/spacy/pipeline/edit_tree_lemmatizer.py
+```
+
+## EditTreeLemmatizer.\_\_init\_\_ {id="init",tag="method"}
+
+> #### Example
+>
+> ```python
+> # Construction via add_pipe with default model
+> lemmatizer = nlp.add_pipe("trainable_lemmatizer", name="lemmatizer")
+>
+> # Construction via create_pipe with custom model
+> config = {"model": {"@architectures": "my_tagger"}}
+> lemmatizer = nlp.add_pipe("trainable_lemmatizer", config=config, name="lemmatizer")
+>
+> # Construction from class
+> from spacy.pipeline import EditTreeLemmatizer
+> lemmatizer = EditTreeLemmatizer(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` | A model instance that predicts the edit tree probabilities. The output vectors should match the number of edit trees in size, and be normalized as probabilities (all scores between 0 and 1, with the rows summing to `1`). ~~Model[List[Doc], List[Floats2d]]~~ |
+| `name` | String name of the component instance. Used to add entries to the `losses` during training. ~~str~~ |
+| _keyword-only_ | |
+| `backoff` | ~~Token~~ attribute to use when no applicable edit tree is found. Defaults to `orth`. ~~str~~ |
+| `min_tree_freq` | Minimum frequency of an edit tree in the training set to be used. Defaults to `3`. ~~int~~ |
+| `overwrite` | Whether existing annotation is overwritten. Defaults to `False`. ~~bool~~ |
+| `top_k` | The number of most probable edit trees to try before resorting to `backoff`. Defaults to `1`. ~~int~~ |
+| `scorer` | The scoring method. Defaults to [`Scorer.score_token_attr`](/api/scorer#score_token_attr) for the attribute `"lemma"`. ~~Optional[Callable]~~ |
+
+## EditTreeLemmatizer.\_\_call\_\_ {id="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/edittreelemmatizer#call) and
+[`pipe`](/api/edittreelemmatizer#pipe) delegate to the
+[`predict`](/api/edittreelemmatizer#predict) and
+[`set_annotations`](/api/edittreelemmatizer#set_annotations) methods.
+
+> #### Example
+>
+> ```python
+> doc = nlp("This is a sentence.")
+> lemmatizer = nlp.add_pipe("trainable_lemmatizer", name="lemmatizer")
+> # This usually happens under the hood
+> processed = lemmatizer(doc)
+> ```
+
+| Name | Description |
+| ----------- | -------------------------------- |
+| `doc` | The document to process. ~~Doc~~ |
+| **RETURNS** | The processed document. ~~Doc~~ |
+
+## EditTreeLemmatizer.pipe {id="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/edittreelemmatizer#call)
+and [`pipe`](/api/edittreelemmatizer#pipe) delegate to the
+[`predict`](/api/edittreelemmatizer#predict) and
+[`set_annotations`](/api/edittreelemmatizer#set_annotations) methods.
+
+> #### Example
+>
+> ```python
+> lemmatizer = nlp.add_pipe("trainable_lemmatizer", name="lemmatizer")
+> for doc in lemmatizer.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~~ |
+
+## EditTreeLemmatizer.initialize {id="initialize",tag="method",version="3"}
+
+Initialize the component for training. `get_examples` should be a function that
+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) and lets you customize
+arguments it receives via the
+[`[initialize.components]`](/api/data-formats#config-initialize) block in the
+config.
+
+> #### Example
+>
+> ```python
+> lemmatizer = nlp.add_pipe("trainable_lemmatizer", name="lemmatizer")
+> lemmatizer.initialize(lambda: examples, nlp=nlp)
+> ```
+>
+> ```ini
+> ### config.cfg
+> [initialize.components.lemmatizer]
+>
+> [initialize.components.lemmatizer.labels]
+> @readers = "spacy.read_labels.v1"
+> path = "corpus/labels/lemmatizer.json
+> ```
+
+| 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]~~ |
+| `labels` | The label information to add to the component, as provided by the [`label_data`](#label_data) property after initialization. To generate a reusable JSON file from your data, you should run the [`init labels`](/api/cli#init-labels) command. If no labels are provided, the `get_examples` callback is used to extract the labels from the data, which may be a lot slower. ~~Optional[Iterable[str]]~~ |
+
+## EditTreeLemmatizer.predict {id="predict",tag="method"}
+
+Apply the component's model to a batch of [`Doc`](/api/doc) objects, without
+modifying them.
+
+> #### Example
+>
+> ```python
+> lemmatizer = nlp.add_pipe("trainable_lemmatizer", name="lemmatizer")
+> tree_ids = lemmatizer.predict([doc1, doc2])
+> ```
+
+| Name | Description |
+| ----------- | ------------------------------------------- |
+| `docs` | The documents to predict. ~~Iterable[Doc]~~ |
+| **RETURNS** | The model's prediction for each document. |
+
+## EditTreeLemmatizer.set_annotations {id="set_annotations",tag="method"}
+
+Modify a batch of [`Doc`](/api/doc) objects, using pre-computed tree
+identifiers.
+
+> #### Example
+>
+> ```python
+> lemmatizer = nlp.add_pipe("trainable_lemmatizer", name="lemmatizer")
+> tree_ids = lemmatizer.predict([doc1, doc2])
+> lemmatizer.set_annotations([doc1, doc2], tree_ids)
+> ```
+
+| Name | Description |
+| ---------- | ------------------------------------------------------------------------------------- |
+| `docs` | The documents to modify. ~~Iterable[Doc]~~ |
+| `tree_ids` | The identifiers of the edit trees to apply, produced by `EditTreeLemmatizer.predict`. |
+
+## EditTreeLemmatizer.update {id="update",tag="method"}
+
+Learn from a batch of [`Example`](/api/example) objects containing the
+predictions and gold-standard annotations, and update the component's model.
+Delegates to [`predict`](/api/edittreelemmatizer#predict) and
+[`get_loss`](/api/edittreelemmatizer#get_loss).
+
+> #### Example
+>
+> ```python
+> lemmatizer = nlp.add_pipe("trainable_lemmatizer", name="lemmatizer")
+> optimizer = nlp.initialize()
+> losses = lemmatizer.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]~~ |
+
+## EditTreeLemmatizer.get_loss {id="get_loss",tag="method"}
+
+Find the loss and gradient of loss for the batch of documents and their
+predicted scores.
+
+> #### Example
+>
+> ```python
+> lemmatizer = nlp.add_pipe("trainable_lemmatizer", name="lemmatizer")
+> scores = lemmatizer.model.begin_update([eg.predicted for eg in examples])
+> loss, d_loss = lemmatizer.get_loss(examples, scores)
+> ```
+
+| Name | Description |
+| ----------- | --------------------------------------------------------------------------- |
+| `examples` | The batch of examples. ~~Iterable[Example]~~ |
+| `scores` | Scores representing the model's predictions. |
+| **RETURNS** | The loss and the gradient, i.e. `(loss, gradient)`. ~~Tuple[float, float]~~ |
+
+## EditTreeLemmatizer.create_optimizer {id="create_optimizer",tag="method"}
+
+Create an optimizer for the pipeline component.
+
+> #### Example
+>
+> ```python
+> lemmatizer = nlp.add_pipe("trainable_lemmatizer", name="lemmatizer")
+> optimizer = lemmatizer.create_optimizer()
+> ```
+
+| Name | Description |
+| ----------- | ---------------------------- |
+| **RETURNS** | The optimizer. ~~Optimizer~~ |
+
+## EditTreeLemmatizer.use_params {id="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
+> lemmatizer = nlp.add_pipe("trainable_lemmatizer", name="lemmatizer")
+> with lemmatizer.use_params(optimizer.averages):
+> lemmatizer.to_disk("/best_model")
+> ```
+
+| Name | Description |
+| -------- | -------------------------------------------------- |
+| `params` | The parameter values to use in the model. ~~dict~~ |
+
+## EditTreeLemmatizer.to_disk {id="to_disk",tag="method"}
+
+Serialize the pipe to disk.
+
+> #### Example
+>
+> ```python
+> lemmatizer = nlp.add_pipe("trainable_lemmatizer", name="lemmatizer")
+> lemmatizer.to_disk("/path/to/lemmatizer")
+> ```
+
+| 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]~~ |
+
+## EditTreeLemmatizer.from_disk {id="from_disk",tag="method"}
+
+Load the pipe from disk. Modifies the object in place and returns it.
+
+> #### Example
+>
+> ```python
+> lemmatizer = nlp.add_pipe("trainable_lemmatizer", name="lemmatizer")
+> lemmatizer.from_disk("/path/to/lemmatizer")
+> ```
+
+| 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 `EditTreeLemmatizer` object. ~~EditTreeLemmatizer~~ |
+
+## EditTreeLemmatizer.to_bytes {id="to_bytes",tag="method"}
+
+> #### Example
+>
+> ```python
+> lemmatizer = nlp.add_pipe("trainable_lemmatizer", name="lemmatizer")
+> lemmatizer_bytes = lemmatizer.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 `EditTreeLemmatizer` object. ~~bytes~~ |
+
+## EditTreeLemmatizer.from_bytes {id="from_bytes",tag="method"}
+
+Load the pipe from a bytestring. Modifies the object in place and returns it.
+
+> #### Example
+>
+> ```python
+> lemmatizer_bytes = lemmatizer.to_bytes()
+> lemmatizer = nlp.add_pipe("trainable_lemmatizer", name="lemmatizer")
+> lemmatizer.from_bytes(lemmatizer_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 `EditTreeLemmatizer` object. ~~EditTreeLemmatizer~~ |
+
+## EditTreeLemmatizer.labels {id="labels",tag="property"}
+
+The labels currently added to the component.
+
+
+
+The `EditTreeLemmatizer` labels are not useful by themselves, since they are
+identifiers of edit trees.
+
+
+
+| Name | Description |
+| ----------- | ------------------------------------------------------ |
+| **RETURNS** | The labels added to the component. ~~Tuple[str, ...]~~ |
+
+## EditTreeLemmatizer.label_data {id="label_data",tag="property",version="3"}
+
+The labels currently added to the component and their internal meta information.
+This is the data generated by [`init labels`](/api/cli#init-labels) and used by
+[`EditTreeLemmatizer.initialize`](/api/edittreelemmatizer#initialize) to
+initialize the model with a pre-defined label set.
+
+> #### Example
+>
+> ```python
+> labels = lemmatizer.label_data
+> lemmatizer.initialize(lambda: [], nlp=nlp, labels=labels)
+> ```
+
+| Name | Description |
+| ----------- | ---------------------------------------------------------- |
+| **RETURNS** | The label data added to the component. ~~Tuple[str, ...]~~ |
+
+## Serialization fields {id="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 = lemmatizer.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. |
+| `trees` | The edit trees. You usually don't want to exclude this. |
diff --git a/website/docs/api/entitylinker.md b/website/docs/api/entitylinker.mdx
similarity index 74%
rename from website/docs/api/entitylinker.md
rename to website/docs/api/entitylinker.mdx
index 3d3372679..bafb2f2da 100644
--- a/website/docs/api/entitylinker.md
+++ b/website/docs/api/entitylinker.mdx
@@ -2,7 +2,7 @@
title: EntityLinker
tag: class
source: spacy/pipeline/entity_linker.py
-new: 2.2
+version: 2.2
teaser: 'Pipeline component for named entity linking and disambiguation'
api_base_class: /api/pipe
api_string_name: entity_linker
@@ -14,9 +14,10 @@ entities) to unique identifiers, grounding the named entities into the "real
world". It requires a `KnowledgeBase`, as well as a function to generate
plausible candidates from that `KnowledgeBase` given a certain textual mention,
and a machine learning model to pick the right candidate, given the local
-context of the mention.
+context of the mention. `EntityLinker` defaults to using the
+[`InMemoryLookupKB`](/api/inmemorylookupkb) implementation.
-## Assigned Attributes {#assigned-attributes}
+## Assigned Attributes {id="assigned-attributes"}
Predictions, in the form of knowledge base IDs, will be assigned to
`Token.ent_kb_id_`.
@@ -26,7 +27,7 @@ Predictions, in the form of knowledge base IDs, will be assigned to
| `Token.ent_kb_id` | Knowledge base ID (hash). ~~int~~ |
| `Token.ent_kb_id_` | Knowledge base ID. ~~str~~ |
-## Config and implementation {#config}
+## Config and implementation {id="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
@@ -47,27 +48,30 @@ architectures and their arguments and hyperparameters.
> "model": DEFAULT_NEL_MODEL,
> "entity_vector_length": 64,
> "get_candidates": {'@misc': 'spacy.CandidateGenerator.v1'},
+> "threshold": None,
> }
> nlp.add_pipe("entity_linker", config=config)
> ```
-| Setting | Description |
-| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `labels_discard` | NER labels that will automatically get a "NIL" prediction. Defaults to `[]`. ~~Iterable[str]~~ |
-| `n_sents` | The number of neighbouring sentences to take into account. Defaults to 0. ~~int~~ |
-| `incl_prior` | Whether or not to include prior probabilities from the KB in the model. Defaults to `True`. ~~bool~~ |
-| `incl_context` | Whether or not to include the local context in the model. Defaults to `True`. ~~bool~~ |
-| `model` | The [`Model`](https://thinc.ai/docs/api-model) powering the pipeline component. Defaults to [EntityLinker](/api/architectures#EntityLinker). ~~Model~~ |
-| `entity_vector_length` | Size of encoding vectors in the KB. Defaults to `64`. ~~int~~ |
-| `get_candidates` | Function that generates plausible candidates for a given `Span` object. Defaults to [CandidateGenerator](/api/architectures#CandidateGenerator), a function looking up exact, case-dependent aliases in the KB. ~~Callable[[KnowledgeBase, Span], Iterable[Candidate]]~~ |
-| `overwrite` 3.2 | Whether existing annotation is overwritten. Defaults to `True`. ~~bool~~ |
-| `scorer` 3.2 | The scoring method. Defaults to [`Scorer.score_links`](/api/scorer#score_links). ~~Optional[Callable]~~ |
+| Setting | Description |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `labels_discard` | NER labels that will automatically get a "NIL" prediction. Defaults to `[]`. ~~Iterable[str]~~ |
+| `n_sents` | The number of neighbouring sentences to take into account. Defaults to 0. ~~int~~ |
+| `incl_prior` | Whether or not to include prior probabilities from the KB in the model. Defaults to `True`. ~~bool~~ |
+| `incl_context` | Whether or not to include the local context in the model. Defaults to `True`. ~~bool~~ |
+| `model` | The [`Model`](https://thinc.ai/docs/api-model) powering the pipeline component. Defaults to [EntityLinker](/api/architectures#EntityLinker). ~~Model~~ |
+| `entity_vector_length` | Size of encoding vectors in the KB. Defaults to `64`. ~~int~~ |
+| `use_gold_ents` | Whether to copy entities from the gold docs or not. Defaults to `True`. If `False`, entities must be set in the training data or by an annotating component in the pipeline. ~~int~~ |
+| `get_candidates` | Function that generates plausible candidates for a given `Span` object. Defaults to [CandidateGenerator](/api/architectures#CandidateGenerator), a function looking up exact, case-dependent aliases in the KB. ~~Callable[[KnowledgeBase, Span], Iterable[Candidate]]~~ |
+| `overwrite` 3.2 | Whether existing annotation is overwritten. Defaults to `True`. ~~bool~~ |
+| `scorer` 3.2 | The scoring method. Defaults to [`Scorer.score_links`](/api/scorer#score_links). ~~Optional[Callable]~~ |
+| `threshold` 3.4 | Confidence threshold for entity predictions. The default of `None` implies that all predictions are accepted, otherwise those with a score beneath the treshold are discarded. If there are no predictions with scores above the threshold, the linked entity is `NIL`. ~~Optional[float]~~ |
```python
%%GITHUB_SPACY/spacy/pipeline/entity_linker.py
```
-## EntityLinker.\_\_init\_\_ {#init tag="method"}
+## EntityLinker.\_\_init\_\_ {id="init",tag="method"}
> #### Example
>
@@ -94,22 +98,23 @@ custom knowledge base, you should either call
[`set_kb`](/api/entitylinker#set_kb) or provide a `kb_loader` in the
[`initialize`](/api/entitylinker#initialize) call.
-| 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_ | |
-| `entity_vector_length` | Size of encoding vectors in the KB. ~~int~~ |
-| `get_candidates` | Function that generates plausible candidates for a given `Span` object. ~~Callable[[KnowledgeBase, Span], Iterable[Candidate]]~~ |
-| `labels_discard` | NER labels that will automatically get a `"NIL"` prediction. ~~Iterable[str]~~ |
-| `n_sents` | The number of neighbouring sentences to take into account. ~~int~~ |
-| `incl_prior` | Whether or not to include prior probabilities from the KB in the model. ~~bool~~ |
-| `incl_context` | Whether or not to include the local context in the model. ~~bool~~ |
-| `overwrite` 3.2 | Whether existing annotation is overwritten. Defaults to `True`. ~~bool~~ |
-| `scorer` 3.2 | The scoring method. Defaults to [`Scorer.score_links`](/api/scorer#score_links). ~~Optional[Callable]~~ |
+| 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_ | |
+| `entity_vector_length` | Size of encoding vectors in the KB. ~~int~~ |
+| `get_candidates` | Function that generates plausible candidates for a given `Span` object. ~~Callable[[KnowledgeBase, Span], Iterable[Candidate]]~~ |
+| `labels_discard` | NER labels that will automatically get a `"NIL"` prediction. ~~Iterable[str]~~ |
+| `n_sents` | The number of neighbouring sentences to take into account. ~~int~~ |
+| `incl_prior` | Whether or not to include prior probabilities from the KB in the model. ~~bool~~ |
+| `incl_context` | Whether or not to include the local context in the model. ~~bool~~ |
+| `overwrite` 3.2 | Whether existing annotation is overwritten. Defaults to `True`. ~~bool~~ |
+| `scorer` 3.2 | The scoring method. Defaults to [`Scorer.score_links`](/api/scorer#score_links). ~~Optional[Callable]~~ |
+| `threshold` 3.4 | Confidence threshold for entity predictions. The default of `None` implies that all predictions are accepted, otherwise those with a score beneath the treshold are discarded. If there are no predictions with scores above the threshold, the linked entity is `NIL`. ~~Optional[float]~~ |
-## EntityLinker.\_\_call\_\_ {#call tag="method"}
+## EntityLinker.\_\_call\_\_ {id="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
@@ -132,7 +137,7 @@ delegate to the [`predict`](/api/entitylinker#predict) and
| `doc` | The document to process. ~~Doc~~ |
| **RETURNS** | The processed document. ~~Doc~~ |
-## EntityLinker.pipe {#pipe tag="method"}
+## EntityLinker.pipe {id="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
@@ -156,7 +161,7 @@ applied to the `Doc` in order. Both [`__call__`](/api/entitylinker#call) and
| `batch_size` | The number of documents to buffer. Defaults to `128`. ~~int~~ |
| **YIELDS** | The processed documents in order. ~~Doc~~ |
-## EntityLinker.set_kb {#set_kb tag="method" new="3"}
+## EntityLinker.set_kb {id="set_kb",tag="method",version="3"}
The `kb_loader` should be a function that takes a `Vocab` instance and creates
the `KnowledgeBase`, ensuring that the strings of the knowledge base are synced
@@ -166,7 +171,7 @@ with the current vocab.
>
> ```python
> def create_kb(vocab):
-> kb = KnowledgeBase(vocab, entity_vector_length=128)
+> kb = InMemoryLookupKB(vocab, entity_vector_length=128)
> kb.add_entity(...)
> kb.add_alias(...)
> return kb
@@ -178,13 +183,13 @@ with the current vocab.
| ----------- | ---------------------------------------------------------------------------------------------------------------- |
| `kb_loader` | Function that creates a [`KnowledgeBase`](/api/kb) from a `Vocab` instance. ~~Callable[[Vocab], KnowledgeBase]~~ |
-## EntityLinker.initialize {#initialize tag="method" new="3"}
+## EntityLinker.initialize {id="initialize",tag="method",version="3"}
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).
@@ -204,17 +209,17 @@ This method was previously called `begin_training`.
>
> ```python
> entity_linker = nlp.add_pipe("entity_linker")
-> entity_linker.initialize(lambda: [], nlp=nlp, kb_loader=my_kb)
+> entity_linker.initialize(lambda: examples, nlp=nlp, kb_loader=my_kb)
> ```
-| 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]~~ |
-| `kb_loader` | Function that creates a [`KnowledgeBase`](/api/kb) from a `Vocab` instance. ~~Callable[[Vocab], KnowledgeBase]~~ |
+| 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]~~ |
+| `kb_loader` | Function that creates a [`KnowledgeBase`](/api/kb) from a `Vocab` instance. ~~Callable[[Vocab], KnowledgeBase]~~ |
-## EntityLinker.predict {#predict tag="method"}
+## EntityLinker.predict {id="predict",tag="method"}
Apply the component's model to a batch of [`Doc`](/api/doc) objects, without
modifying them. Returns the KB IDs for each entity in each doc, including `NIL`
@@ -232,7 +237,7 @@ if there is no prediction.
| `docs` | The documents to predict. ~~Iterable[Doc]~~ |
| **RETURNS** | The predicted KB identifiers for the entities in the `docs`. ~~List[str]~~ |
-## EntityLinker.set_annotations {#set_annotations tag="method"}
+## EntityLinker.set_annotations {id="set_annotations",tag="method"}
Modify a batch of documents, using pre-computed entity IDs for a list of named
entities.
@@ -250,7 +255,7 @@ entities.
| `docs` | The documents to modify. ~~Iterable[Doc]~~ |
| `kb_ids` | The knowledge base identifiers for the entities in the docs, predicted by `EntityLinker.predict`. ~~List[str]~~ |
-## EntityLinker.update {#update tag="method"}
+## EntityLinker.update {id="update",tag="method"}
Learn from a batch of [`Example`](/api/example) objects, updating both the
pipe's entity linking model and context encoder. Delegates to
@@ -273,7 +278,7 @@ pipe's entity linking model and context encoder. Delegates to
| `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]~~ |
-## EntityLinker.create_optimizer {#create_optimizer tag="method"}
+## EntityLinker.create_optimizer {id="create_optimizer",tag="method"}
Create an optimizer for the pipeline component.
@@ -288,7 +293,7 @@ Create an optimizer for the pipeline component.
| ----------- | ---------------------------- |
| **RETURNS** | The optimizer. ~~Optimizer~~ |
-## EntityLinker.use_params {#use_params tag="method, contextmanager"}
+## EntityLinker.use_params {id="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.
@@ -305,7 +310,7 @@ context, the original parameters are restored.
| -------- | -------------------------------------------------- |
| `params` | The parameter values to use in the model. ~~dict~~ |
-## EntityLinker.to_disk {#to_disk tag="method"}
+## EntityLinker.to_disk {id="to_disk",tag="method"}
Serialize the pipe to disk.
@@ -322,7 +327,7 @@ Serialize the pipe to disk.
| _keyword-only_ | |
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
-## EntityLinker.from_disk {#from_disk tag="method"}
+## EntityLinker.from_disk {id="from_disk",tag="method"}
Load the pipe from disk. Modifies the object in place and returns it.
@@ -340,7 +345,7 @@ Load the pipe from disk. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The modified `EntityLinker` object. ~~EntityLinker~~ |
-## EntityLinker.to_bytes {#to_bytes tag="method"}
+## EntityLinker.to_bytes {id="to_bytes",tag="method"}
> #### Example
>
@@ -357,7 +362,7 @@ Serialize the pipe to a bytestring, including the `KnowledgeBase`.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The serialized form of the `EntityLinker` object. ~~bytes~~ |
-## EntityLinker.from_bytes {#from_bytes tag="method"}
+## EntityLinker.from_bytes {id="from_bytes",tag="method"}
Load the pipe from a bytestring. Modifies the object in place and returns it.
@@ -376,7 +381,7 @@ Load the pipe from a bytestring. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The `EntityLinker` object. ~~EntityLinker~~ |
-## Serialization fields {#serialization-fields}
+## Serialization fields {id="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
diff --git a/website/docs/api/entityrecognizer.md b/website/docs/api/entityrecognizer.mdx
similarity index 92%
rename from website/docs/api/entityrecognizer.md
rename to website/docs/api/entityrecognizer.mdx
index 14b6fece4..c80406a5b 100644
--- a/website/docs/api/entityrecognizer.md
+++ b/website/docs/api/entityrecognizer.mdx
@@ -20,7 +20,7 @@ your entities will be close to their initial tokens. If your entities are long
and characterized by tokens in their middle, the component will likely not be a
good fit for your task.
-## Assigned Attributes {#assigned-attributes}
+## Assigned Attributes {id="assigned-attributes"}
Predictions will be saved to `Doc.ents` as a tuple. Each label will also be
reflected to each underlying token, where it is saved in the `Token.ent_type`
@@ -38,7 +38,7 @@ non-overlapping, or an error will be thrown.
| `Token.ent_type` | The label part of the named entity tag (hash). ~~int~~ |
| `Token.ent_type_` | The label part of the named entity tag. ~~str~~ |
-## Config and implementation {#config}
+## Config and implementation {id="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
@@ -62,7 +62,7 @@ architectures and their arguments and hyperparameters.
| Setting | Description |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `moves` | A list of transition names. Inferred from the data if not provided. Defaults to `None`. ~~Optional[List[str]]~~ |
+| `moves` | A list of transition names. Inferred from the data if not provided. Defaults to `None`. ~~Optional[TransitionSystem]~~ |
| `update_with_oracle_cut_size` | During training, cut long sequences into shorter segments by creating intermediate states based on the gold-standard history. The model is not very sensitive to this parameter, so you usually won't need to change it. Defaults to `100`. ~~int~~ |
| `model` | The [`Model`](https://thinc.ai/docs/api-model) powering the pipeline component. Defaults to [TransitionBasedParser](/api/architectures#TransitionBasedParser). ~~Model[List[Doc], List[Floats2d]]~~ |
| `incorrect_spans_key` | This key refers to a `SpanGroup` in `doc.spans` that specifies incorrect spans. The NER will learn not to predict (exactly) those spans. Defaults to `None`. ~~Optional[str]~~ |
@@ -72,7 +72,7 @@ architectures and their arguments and hyperparameters.
%%GITHUB_SPACY/spacy/pipeline/ner.pyx
```
-## EntityRecognizer.\_\_init\_\_ {#init tag="method"}
+## EntityRecognizer.\_\_init\_\_ {id="init",tag="method"}
> #### Example
>
@@ -98,12 +98,12 @@ shortcut for this and instantiate the component using its string name and
| `vocab` | The shared vocabulary. ~~Vocab~~ |
| `model` | The [`Model`](https://thinc.ai/docs/api-model) powering the pipeline component. ~~Model[List[Doc], List[Floats2d]]~~ |
| `name` | String name of the component instance. Used to add entries to the `losses` during training. ~~str~~ |
-| `moves` | A list of transition names. Inferred from the data if set to `None`, which is the default. ~~Optional[List[str]]~~ |
+| `moves` | A list of transition names. Inferred from the data if set to `None`, which is the default. ~~Optional[TransitionSystem]~~ |
| _keyword-only_ | |
| `update_with_oracle_cut_size` | During training, cut long sequences into shorter segments by creating intermediate states based on the gold-standard history. The model is not very sensitive to this parameter, so you usually won't need to change it. Defaults to `100`. ~~int~~ |
| `incorrect_spans_key` | Identifies spans that are known to be incorrect entity annotations. The incorrect entity annotations can be stored in the span group in [`Doc.spans`](/api/doc#spans), under this key. Defaults to `None`. ~~Optional[str]~~ |
-## EntityRecognizer.\_\_call\_\_ {#call tag="method"}
+## EntityRecognizer.\_\_call\_\_ {id="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
@@ -127,7 +127,7 @@ and all pipeline components are applied to the `Doc` in order. Both
| `doc` | The document to process. ~~Doc~~ |
| **RETURNS** | The processed document. ~~Doc~~ |
-## EntityRecognizer.pipe {#pipe tag="method"}
+## EntityRecognizer.pipe {id="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
@@ -151,13 +151,13 @@ applied to the `Doc` in order. Both [`__call__`](/api/entityrecognizer#call) and
| `batch_size` | The number of documents to buffer. Defaults to `128`. ~~int~~ |
| **YIELDS** | The processed documents in order. ~~Doc~~ |
-## EntityRecognizer.initialize {#initialize tag="method" new="3"}
+## EntityRecognizer.initialize {id="initialize",tag="method",version="3"}
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) and lets you customize
@@ -175,7 +175,7 @@ This method was previously called `begin_training`.
>
> ```python
> ner = nlp.add_pipe("ner")
-> ner.initialize(lambda: [], nlp=nlp)
+> ner.initialize(lambda: examples, nlp=nlp)
> ```
>
> ```ini
@@ -189,12 +189,12 @@ This method was previously called `begin_training`.
| Name | Description |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `get_examples` | Function that returns gold-standard annotations in the form of [`Example`](/api/example) objects. ~~Callable[[], Iterable[Example]]~~ |
+| `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]~~ |
| `labels` | The label information to add to the component, as provided by the [`label_data`](#label_data) property after initialization. To generate a reusable JSON file from your data, you should run the [`init labels`](/api/cli#init-labels) command. If no labels are provided, the `get_examples` callback is used to extract the labels from the data, which may be a lot slower. ~~Optional[Dict[str, Dict[str, int]]]~~ |
-## EntityRecognizer.predict {#predict tag="method"}
+## EntityRecognizer.predict {id="predict",tag="method"}
Apply the component's model to a batch of [`Doc`](/api/doc) objects, without
modifying them.
@@ -211,7 +211,7 @@ modifying them.
| `docs` | The documents to predict. ~~Iterable[Doc]~~ |
| **RETURNS** | A helper class for the parse state (internal). ~~StateClass~~ |
-## EntityRecognizer.set_annotations {#set_annotations tag="method"}
+## EntityRecognizer.set_annotations {id="set_annotations",tag="method"}
Modify a batch of [`Doc`](/api/doc) objects, using pre-computed scores.
@@ -228,7 +228,7 @@ Modify a batch of [`Doc`](/api/doc) objects, using pre-computed scores.
| `docs` | The documents to modify. ~~Iterable[Doc]~~ |
| `scores` | The scores to set, produced by `EntityRecognizer.predict`. Returns an internal helper class for the parse state. ~~List[StateClass]~~ |
-## EntityRecognizer.update {#update tag="method"}
+## EntityRecognizer.update {id="update",tag="method"}
Learn from a batch of [`Example`](/api/example) objects, updating the pipe's
model. Delegates to [`predict`](/api/entityrecognizer#predict) and
@@ -251,7 +251,7 @@ model. Delegates to [`predict`](/api/entityrecognizer#predict) and
| `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]~~ |
-## EntityRecognizer.get_loss {#get_loss tag="method"}
+## EntityRecognizer.get_loss {id="get_loss",tag="method"}
Find the loss and gradient of loss for the batch of documents and their
predicted scores.
@@ -270,7 +270,7 @@ predicted scores.
| `scores` | Scores representing the model's predictions. ~~StateClass~~ |
| **RETURNS** | The loss and the gradient, i.e. `(loss, gradient)`. ~~Tuple[float, float]~~ |
-## EntityRecognizer.create_optimizer {#create_optimizer tag="method"}
+## EntityRecognizer.create_optimizer {id="create_optimizer",tag="method"}
Create an optimizer for the pipeline component.
@@ -285,7 +285,7 @@ Create an optimizer for the pipeline component.
| ----------- | ---------------------------- |
| **RETURNS** | The optimizer. ~~Optimizer~~ |
-## EntityRecognizer.use_params {#use_params tag="method, contextmanager"}
+## EntityRecognizer.use_params {id="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.
@@ -302,7 +302,7 @@ context, the original parameters are restored.
| -------- | -------------------------------------------------- |
| `params` | The parameter values to use in the model. ~~dict~~ |
-## EntityRecognizer.add_label {#add_label tag="method"}
+## EntityRecognizer.add_label {id="add_label",tag="method"}
Add a new label to the pipe. Note that you don't have to call this method if you
provide a **representative data sample** to the [`initialize`](#initialize)
@@ -322,7 +322,7 @@ to the model, and the output dimension will be
| `label` | The label to add. ~~str~~ |
| **RETURNS** | `0` if the label is already present, otherwise `1`. ~~int~~ |
-## EntityRecognizer.set_output {#set_output tag="method"}
+## EntityRecognizer.set_output {id="set_output",tag="method"}
Change the output dimension of the component's model by calling the model's
attribute `resize_output`. This is a function that takes the original model and
@@ -341,7 +341,7 @@ forgetting" problem.
| ---- | --------------------------------- |
| `nO` | The new output dimension. ~~int~~ |
-## EntityRecognizer.to_disk {#to_disk tag="method"}
+## EntityRecognizer.to_disk {id="to_disk",tag="method"}
Serialize the pipe to disk.
@@ -358,7 +358,7 @@ Serialize the pipe to disk.
| _keyword-only_ | |
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
-## EntityRecognizer.from_disk {#from_disk tag="method"}
+## EntityRecognizer.from_disk {id="from_disk",tag="method"}
Load the pipe from disk. Modifies the object in place and returns it.
@@ -376,7 +376,7 @@ Load the pipe from disk. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The modified `EntityRecognizer` object. ~~EntityRecognizer~~ |
-## EntityRecognizer.to_bytes {#to_bytes tag="method"}
+## EntityRecognizer.to_bytes {id="to_bytes",tag="method"}
> #### Example
>
@@ -393,7 +393,7 @@ Serialize the pipe to a bytestring.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The serialized form of the `EntityRecognizer` object. ~~bytes~~ |
-## EntityRecognizer.from_bytes {#from_bytes tag="method"}
+## EntityRecognizer.from_bytes {id="from_bytes",tag="method"}
Load the pipe from a bytestring. Modifies the object in place and returns it.
@@ -412,7 +412,7 @@ Load the pipe from a bytestring. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The `EntityRecognizer` object. ~~EntityRecognizer~~ |
-## EntityRecognizer.labels {#labels tag="property"}
+## EntityRecognizer.labels {id="labels",tag="property"}
The labels currently added to the component.
@@ -427,7 +427,7 @@ The labels currently added to the component.
| ----------- | ------------------------------------------------------ |
| **RETURNS** | The labels added to the component. ~~Tuple[str, ...]~~ |
-## EntityRecognizer.label_data {#label_data tag="property" new="3"}
+## EntityRecognizer.label_data {id="label_data",tag="property",version="3"}
The labels currently added to the component and their internal meta information.
This is the data generated by [`init labels`](/api/cli#init-labels) and used by
@@ -445,7 +445,7 @@ the model with a pre-defined label set.
| ----------- | ------------------------------------------------------------------------------- |
| **RETURNS** | The label data added to the component. ~~Dict[str, Dict[str, Dict[str, int]]]~~ |
-## Serialization fields {#serialization-fields}
+## Serialization fields {id="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
diff --git a/website/docs/api/entityruler.md b/website/docs/api/entityruler.mdx
similarity index 69%
rename from website/docs/api/entityruler.md
rename to website/docs/api/entityruler.mdx
index 1ef283870..27624398e 100644
--- a/website/docs/api/entityruler.md
+++ b/website/docs/api/entityruler.mdx
@@ -2,7 +2,7 @@
title: EntityRuler
tag: class
source: spacy/pipeline/entityruler.py
-new: 2.1
+version: 2.1
teaser: 'Pipeline component for rule-based named entity recognition'
api_string_name: entity_ruler
api_trainable: false
@@ -15,7 +15,7 @@ used on its own to implement a purely rule-based entity recognition system. For
usage examples, see the docs on
[rule-based entity recognition](/usage/rule-based-matching#entityruler).
-## Assigned Attributes {#assigned-attributes}
+## Assigned Attributes {id="assigned-attributes"}
This component assigns predictions basically the same way as the
[`EntityRecognizer`](/api/entityrecognizer).
@@ -36,7 +36,7 @@ non-overlapping, or an error will be thrown.
| `Token.ent_type` | The label part of the named entity tag (hash). ~~int~~ |
| `Token.ent_type_` | The label part of the named entity tag. ~~str~~ |
-## Config and implementation {#config}
+## Config and implementation {id="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
@@ -55,19 +55,20 @@ how the component should be configured. You can override its settings via the
> nlp.add_pipe("entity_ruler", config=config)
> ```
-| Setting | Description |
-| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `phrase_matcher_attr` | Optional attribute name match on for the internal [`PhraseMatcher`](/api/phrasematcher), e.g. `LOWER` to match on the lowercase token text. Defaults to `None`. ~~Optional[Union[int, str]]~~ |
-| `validate` | Whether patterns should be validated (passed to the `Matcher` and `PhraseMatcher`). Defaults to `False`. ~~bool~~ |
-| `overwrite_ents` | If existing entities are present, e.g. entities added by the model, overwrite them by matches if necessary. Defaults to `False`. ~~bool~~ |
-| `ent_id_sep` | Separator used internally for entity IDs. Defaults to `"\|\|"`. ~~str~~ |
-| `scorer` | The scoring method. Defaults to [`spacy.scorer.get_ner_prf`](/api/scorer#get_ner_prf). ~~Optional[Callable]~~ |
+| Setting | Description |
+| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `phrase_matcher_attr` | Optional attribute name match on for the internal [`PhraseMatcher`](/api/phrasematcher), e.g. `LOWER` to match on the lowercase token text. Defaults to `None`. ~~Optional[Union[int, str]]~~ |
+| `matcher_fuzzy_compare` 3.5 | The fuzzy comparison method, passed on to the internal `Matcher`. Defaults to `spacy.matcher.levenshtein.levenshtein_compare`. ~~Callable~~ |
+| `validate` | Whether patterns should be validated (passed to the `Matcher` and `PhraseMatcher`). Defaults to `False`. ~~bool~~ |
+| `overwrite_ents` | If existing entities are present, e.g. entities added by the model, overwrite them by matches if necessary. Defaults to `False`. ~~bool~~ |
+| `ent_id_sep` | Separator used internally for entity IDs. Defaults to `"\|\|"`. ~~str~~ |
+| `scorer` | The scoring method. Defaults to [`spacy.scorer.get_ner_prf`](/api/scorer#get_ner_prf). ~~Optional[Callable]~~ |
```python
%%GITHUB_SPACY/spacy/pipeline/entityruler.py
```
-## EntityRuler.\_\_init\_\_ {#init tag="method"}
+## EntityRuler.\_\_init\_\_ {id="init",tag="method"}
Initialize the entity ruler. If patterns are supplied here, they need to be a
list of dictionaries with a `"label"` and `"pattern"` key. A pattern can either
@@ -85,23 +86,25 @@ be a token pattern (list) or a phrase pattern (string). For example:
> ruler = EntityRuler(nlp, overwrite_ents=True)
> ```
-| Name | Description |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `nlp` | The shared nlp object to pass the vocab to the matchers and process phrase patterns. ~~Language~~ |
-| `name` 3 | Instance name of the current pipeline component. Typically passed in automatically from the factory when the component is added. Used to disable the current entity ruler while creating phrase patterns with the nlp object. ~~str~~ |
-| _keyword-only_ | |
-| `phrase_matcher_attr` | Optional attribute name match on for the internal [`PhraseMatcher`](/api/phrasematcher), e.g. `LOWER` to match on the lowercase token text. Defaults to `None`. ~~Optional[Union[int, str]]~~ |
-| `validate` | Whether patterns should be validated, passed to Matcher and PhraseMatcher as `validate`. Defaults to `False`. ~~bool~~ |
-| `overwrite_ents` | If existing entities are present, e.g. entities added by the model, overwrite them by matches if necessary. Defaults to `False`. ~~bool~~ |
-| `ent_id_sep` | Separator used internally for entity IDs. Defaults to `"\|\|"`. ~~str~~ |
-| `patterns` | Optional patterns to load in on initialization. ~~Optional[List[Dict[str, Union[str, List[dict]]]]]~~ |
+| Name | Description |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `nlp` | The shared nlp object to pass the vocab to the matchers and process phrase patterns. ~~Language~~ |
+| `name` 3 | Instance name of the current pipeline component. Typically passed in automatically from the factory when the component is added. Used to disable the current entity ruler while creating phrase patterns with the nlp object. ~~str~~ |
+| _keyword-only_ | |
+| `phrase_matcher_attr` | Optional attribute name match on for the internal [`PhraseMatcher`](/api/phrasematcher), e.g. `LOWER` to match on the lowercase token text. Defaults to `None`. ~~Optional[Union[int, str]]~~ |
+| `matcher_fuzzy_compare` 3.5 | The fuzzy comparison method, passed on to the internal `Matcher`. Defaults to `spacy.matcher.levenshtein.levenshtein_compare`. ~~Callable~~ |
+| `validate` | Whether patterns should be validated, passed to Matcher and PhraseMatcher as `validate`. Defaults to `False`. ~~bool~~ |
+| `overwrite_ents` | If existing entities are present, e.g. entities added by the model, overwrite them by matches if necessary. Defaults to `False`. ~~bool~~ |
+| `ent_id_sep` | Separator used internally for entity IDs. Defaults to `"\|\|"`. ~~str~~ |
+| `patterns` | Optional patterns to load in on initialization. ~~Optional[List[Dict[str, Union[str, List[dict]]]]]~~ |
+| `scorer` | The scoring method. Defaults to [`spacy.scorer.get_ner_prf`](/api/scorer#get_ner_prf). ~~Optional[Callable]~~ |
-## EntityRuler.initialize {#initialize tag="method" new="3"}
+## EntityRuler.initialize {id="initialize",tag="method",version="3"}
Initialize the component with data and used before training to load in rules
-from a [pattern file](/usage/rule-based-matching/#entityruler-files). This method
-is typically called by [`Language.initialize`](/api/language#initialize) and
-lets you customize arguments it receives via the
+from a [pattern file](/usage/rule-based-matching/#entityruler-files). This
+method is typically called by [`Language.initialize`](/api/language#initialize)
+and lets you customize arguments it receives via the
[`[initialize.components]`](/api/data-formats#config-initialize) block in the
config.
@@ -128,7 +131,7 @@ config.
| `nlp` | The current `nlp` object. Defaults to `None`. ~~Optional[Language]~~ |
| `patterns` | The list of patterns. Defaults to `None`. ~~Optional[Sequence[Dict[str, Union[str, List[Dict[str, Any]]]]]]~~ |
-## EntityRuler.\_\len\_\_ {#len tag="method"}
+## EntityRuler.\_\_len\_\_ {id="len",tag="method"}
The number of all patterns added to the entity ruler.
@@ -145,7 +148,7 @@ The number of all patterns added to the entity ruler.
| ----------- | ------------------------------- |
| **RETURNS** | The number of patterns. ~~int~~ |
-## EntityRuler.\_\_contains\_\_ {#contains tag="method"}
+## EntityRuler.\_\_contains\_\_ {id="contains",tag="method"}
Whether a label is present in the patterns.
@@ -163,7 +166,7 @@ Whether a label is present in the patterns.
| `label` | The label to check. ~~str~~ |
| **RETURNS** | Whether the entity ruler contains the label. ~~bool~~ |
-## EntityRuler.\_\_call\_\_ {#call tag="method"}
+## EntityRuler.\_\_call\_\_ {id="call",tag="method"}
Find matches in the `Doc` and add them to the `doc.ents`. Typically, this
happens automatically after the component has been added to the pipeline using
@@ -189,7 +192,7 @@ is chosen.
| `doc` | The `Doc` object to process, e.g. the `Doc` in the pipeline. ~~Doc~~ |
| **RETURNS** | The modified `Doc` with added entities, if available. ~~Doc~~ |
-## EntityRuler.add_patterns {#add_patterns tag="method"}
+## EntityRuler.add_patterns {id="add_patterns",tag="method"}
Add patterns to the entity ruler. A pattern can either be a token pattern (list
of dicts) or a phrase pattern (string). For more details, see the usage guide on
@@ -210,10 +213,10 @@ of dicts) or a phrase pattern (string). For more details, see the usage guide on
| ---------- | ---------------------------------------------------------------- |
| `patterns` | The patterns to add. ~~List[Dict[str, Union[str, List[dict]]]]~~ |
+## EntityRuler.remove {id="remove",tag="method",version="3.2.1"}
-## EntityRuler.remove {#remove tag="method" new="3.2.1"}
-
-Remove a pattern by its ID from the entity ruler. A `ValueError` is raised if the ID does not exist.
+Remove a pattern by its ID from the entity ruler. A `ValueError` is raised if
+the ID does not exist.
> #### Example
>
@@ -224,11 +227,11 @@ Remove a pattern by its ID from the entity ruler. A `ValueError` is raised if th
> ruler.remove("apple")
> ```
-| Name | Description |
-| ---------- | ---------------------------------------------------------------- |
-| `id` | The ID of the pattern rule. ~~str~~ |
+| Name | Description |
+| ---- | ----------------------------------- |
+| `id` | The ID of the pattern rule. ~~str~~ |
-## EntityRuler.to_disk {#to_disk tag="method"}
+## EntityRuler.to_disk {id="to_disk",tag="method"}
Save the entity ruler patterns to a directory. The patterns will be saved as
newline-delimited JSON (JSONL). If a file with the suffix `.jsonl` is provided,
@@ -247,7 +250,7 @@ only the patterns are saved as JSONL. If a directory name is provided, a
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `path` | A path to a JSONL file or directory, which will be created if it doesn't exist. Paths may be either strings or `Path`-like objects. ~~Union[str, Path]~~ |
-## EntityRuler.from_disk {#from_disk tag="method"}
+## EntityRuler.from_disk {id="from_disk",tag="method"}
Load the entity ruler from a path. Expects either a file containing
newline-delimited JSON (JSONL) with one entry per line, or a directory
@@ -267,7 +270,7 @@ configuration.
| `path` | A path to a JSONL file or directory. Paths may be either strings or `Path`-like objects. ~~Union[str, Path]~~ |
| **RETURNS** | The modified `EntityRuler` object. ~~EntityRuler~~ |
-## EntityRuler.to_bytes {#to_bytes tag="method"}
+## EntityRuler.to_bytes {id="to_bytes",tag="method"}
Serialize the entity ruler patterns to a bytestring.
@@ -282,7 +285,7 @@ Serialize the entity ruler patterns to a bytestring.
| ----------- | ---------------------------------- |
| **RETURNS** | The serialized patterns. ~~bytes~~ |
-## EntityRuler.from_bytes {#from_bytes tag="method"}
+## EntityRuler.from_bytes {id="from_bytes",tag="method"}
Load the pipe from a bytestring. Modifies the object in place and returns it.
@@ -290,7 +293,7 @@ Load the pipe from a bytestring. Modifies the object in place and returns it.
>
> ```python
> ruler_bytes = ruler.to_bytes()
-> ruler = nlp.add_pipe("enity_ruler")
+> ruler = nlp.add_pipe("entity_ruler")
> ruler.from_bytes(ruler_bytes)
> ```
@@ -299,7 +302,7 @@ Load the pipe from a bytestring. Modifies the object in place and returns it.
| `bytes_data` | The bytestring to load. ~~bytes~~ |
| **RETURNS** | The modified `EntityRuler` object. ~~EntityRuler~~ |
-## EntityRuler.labels {#labels tag="property"}
+## EntityRuler.labels {id="labels",tag="property"}
All labels present in the match patterns.
@@ -307,7 +310,7 @@ All labels present in the match patterns.
| ----------- | -------------------------------------- |
| **RETURNS** | The string labels. ~~Tuple[str, ...]~~ |
-## EntityRuler.ent_ids {#ent_ids tag="property" new="2.2.2"}
+## EntityRuler.ent_ids {id="ent_ids",tag="property",version="2.2.2"}
All entity IDs present in the `id` properties of the match patterns.
@@ -315,7 +318,7 @@ All entity IDs present in the `id` properties of the match patterns.
| ----------- | ----------------------------------- |
| **RETURNS** | The string IDs. ~~Tuple[str, ...]~~ |
-## EntityRuler.patterns {#patterns tag="property"}
+## EntityRuler.patterns {id="patterns",tag="property"}
Get all patterns that were added to the entity ruler.
@@ -323,7 +326,7 @@ Get all patterns that were added to the entity ruler.
| ----------- | ---------------------------------------------------------------------------------------- |
| **RETURNS** | The original patterns, one dictionary per pattern. ~~List[Dict[str, Union[str, dict]]]~~ |
-## Attributes {#attributes}
+## Attributes {id="attributes"}
| Name | Description |
| ----------------- | --------------------------------------------------------------------------------------------------------------------- |
diff --git a/website/docs/api/example.md b/website/docs/api/example.mdx
similarity index 87%
rename from website/docs/api/example.md
rename to website/docs/api/example.mdx
index ca9d3c056..a29d5a7e0 100644
--- a/website/docs/api/example.md
+++ b/website/docs/api/example.mdx
@@ -3,7 +3,7 @@ title: Example
teaser: A training instance
tag: class
source: spacy/training/example.pyx
-new: 3.0
+version: 3.0
---
An `Example` holds the information for one training instance. It stores two
@@ -12,7 +12,7 @@ holding the predictions of the pipeline. An
[`Alignment`](/api/example#alignment-object) object stores the alignment between
these two documents, as they can differ in tokenization.
-## Example.\_\_init\_\_ {#init tag="method"}
+## Example.\_\_init\_\_ {id="init",tag="method"}
Construct an `Example` object from the `predicted` document and the `reference`
document. If `alignment` is `None`, it will be initialized from the words in
@@ -23,11 +23,13 @@ both documents.
> ```python
> from spacy.tokens import Doc
> from spacy.training import Example
->
-> words = ["hello", "world", "!"]
-> spaces = [True, False, False]
-> predicted = Doc(nlp.vocab, words=words, spaces=spaces)
-> reference = parse_gold_doc(my_data)
+> pred_words = ["Apply", "some", "sunscreen"]
+> pred_spaces = [True, True, False]
+> gold_words = ["Apply", "some", "sun", "screen"]
+> gold_spaces = [True, True, False, False]
+> gold_tags = ["VERB", "DET", "NOUN", "NOUN"]
+> predicted = Doc(nlp.vocab, words=pred_words, spaces=pred_spaces)
+> reference = Doc(nlp.vocab, words=gold_words, spaces=gold_spaces, tags=gold_tags)
> example = Example(predicted, reference)
> ```
@@ -38,7 +40,7 @@ both documents.
| _keyword-only_ | |
| `alignment` | An object holding the alignment between the tokens of the `predicted` and `reference` documents. ~~Optional[Alignment]~~ |
-## Example.from_dict {#from_dict tag="classmethod"}
+## Example.from_dict {id="from_dict",tag="classmethod"}
Construct an `Example` object from the `predicted` document and the reference
annotations provided as a dictionary. For more details on the required format,
@@ -62,7 +64,7 @@ see the [training format documentation](/api/data-formats#dict-input).
| `example_dict` | The gold-standard annotations as a dictionary. Cannot be `None`. ~~Dict[str, Any]~~ |
| **RETURNS** | The newly constructed object. ~~Example~~ |
-## Example.text {#text tag="property"}
+## Example.text {id="text",tag="property"}
The text of the `predicted` document in this `Example`.
@@ -76,7 +78,7 @@ The text of the `predicted` document in this `Example`.
| ----------- | --------------------------------------------- |
| **RETURNS** | The text of the `predicted` document. ~~str~~ |
-## Example.predicted {#predicted tag="property"}
+## Example.predicted {id="predicted",tag="property"}
The `Doc` holding the predictions. Occasionally also referred to as `example.x`.
@@ -92,7 +94,7 @@ The `Doc` holding the predictions. Occasionally also referred to as `example.x`.
| ----------- | ------------------------------------------------------ |
| **RETURNS** | The document containing (partial) predictions. ~~Doc~~ |
-## Example.reference {#reference tag="property"}
+## Example.reference {id="reference",tag="property"}
The `Doc` holding the gold-standard annotations. Occasionally also referred to
as `example.y`.
@@ -109,7 +111,7 @@ as `example.y`.
| ----------- | ---------------------------------------------------------- |
| **RETURNS** | The document containing gold-standard annotations. ~~Doc~~ |
-## Example.alignment {#alignment tag="property"}
+## Example.alignment {id="alignment",tag="property"}
The [`Alignment`](/api/example#alignment-object) object mapping the tokens of
the `predicted` document to those of the `reference` document.
@@ -129,7 +131,7 @@ the `predicted` document to those of the `reference` document.
| ----------- | ---------------------------------------------------------------- |
| **RETURNS** | The document containing gold-standard annotations. ~~Alignment~~ |
-## Example.get_aligned {#get_aligned tag="method"}
+## Example.get_aligned {id="get_aligned",tag="method"}
Get the aligned view of a certain token attribute, denoted by its int ID or
string name.
@@ -150,7 +152,7 @@ string name.
| `as_string` | Whether or not to return the list of values as strings. Defaults to `False`. ~~bool~~ |
| **RETURNS** | List of integer values, or string values if `as_string` is `True`. ~~Union[List[int], List[str]]~~ |
-## Example.get_aligned_parse {#get_aligned_parse tag="method"}
+## Example.get_aligned_parse {id="get_aligned_parse",tag="method"}
Get the aligned view of the dependency parse. If `projectivize` is set to
`True`, non-projective dependency trees are made projective through the
@@ -170,7 +172,7 @@ Pseudo-Projective Dependency Parsing algorithm by Nivre and Nilsson (2005).
| `projectivize` | Whether or not to projectivize the dependency trees. Defaults to `True`. ~~bool~~ |
| **RETURNS** | List of integer values, or string values if `as_string` is `True`. ~~Union[List[int], List[str]]~~ |
-## Example.get_aligned_ner {#get_aligned_ner tag="method"}
+## Example.get_aligned_ner {id="get_aligned_ner",tag="method"}
Get the aligned view of the NER
[BILUO](/usage/linguistic-features#accessing-ner) tags.
@@ -191,7 +193,7 @@ Get the aligned view of the NER
| ----------- | ------------------------------------------------------------------------------------------------- |
| **RETURNS** | List of BILUO values, denoting whether tokens are part of an NER annotation or not. ~~List[str]~~ |
-## Example.get_aligned_spans_y2x {#get_aligned_spans_y2x tag="method"}
+## Example.get_aligned_spans_y2x {id="get_aligned_spans_y2x",tag="method"}
Get the aligned view of any set of [`Span`](/api/span) objects defined over
[`Example.reference`](/api/example#reference). The resulting span indices will
@@ -217,7 +219,7 @@ align to the tokenization in [`Example.predicted`](/api/example#predicted).
| `allow_overlap` | Whether the resulting `Span` objects may overlap or not. Set to `False` by default. ~~bool~~ |
| **RETURNS** | `Span` objects aligned to the tokenization of `predicted`. ~~List[Span]~~ |
-## Example.get_aligned_spans_x2y {#get_aligned_spans_x2y tag="method"}
+## Example.get_aligned_spans_x2y {id="get_aligned_spans_x2y",tag="method"}
Get the aligned view of any set of [`Span`](/api/span) objects defined over
[`Example.predicted`](/api/example#predicted). The resulting span indices will
@@ -245,7 +247,7 @@ against the original gold-standard annotation.
| `allow_overlap` | Whether the resulting `Span` objects may overlap or not. Set to `False` by default. ~~bool~~ |
| **RETURNS** | `Span` objects aligned to the tokenization of `reference`. ~~List[Span]~~ |
-## Example.to_dict {#to_dict tag="method"}
+## Example.to_dict {id="to_dict",tag="method"}
Return a [dictionary representation](/api/data-formats#dict-input) of the
reference annotation contained in this `Example`.
@@ -260,7 +262,7 @@ reference annotation contained in this `Example`.
| ----------- | ------------------------------------------------------------------------- |
| **RETURNS** | Dictionary representation of the reference annotation. ~~Dict[str, Any]~~ |
-## Example.split_sents {#split_sents tag="method"}
+## Example.split_sents {id="split_sents",tag="method"}
Split one `Example` into multiple `Example` objects, one for each sentence.
@@ -280,16 +282,20 @@ Split one `Example` into multiple `Example` objects, one for each sentence.
| ----------- | ---------------------------------------------------------------------------- |
| **RETURNS** | List of `Example` objects, one for each original sentence. ~~List[Example]~~ |
-## Alignment {#alignment-object new="3"}
+## Alignment {id="alignment-object",version="3"}
Calculate alignment tables between two tokenizations.
-### Alignment attributes {#alignment-attributes"}
+### Alignment attributes {id="alignment-attributes"}
-| Name | Description |
-| ----- | --------------------------------------------------------------------- |
-| `x2y` | The `Ragged` object holding the alignment from `x` to `y`. ~~Ragged~~ |
-| `y2x` | The `Ragged` object holding the alignment from `y` to `x`. ~~Ragged~~ |
+Alignment attributes are managed using `AlignmentArray`, which is a simplified
+version of Thinc's [Ragged](https://thinc.ai/docs/api-types#ragged) type that
+only supports the `data` and `length` attributes.
+
+| Name | Description |
+| ----- | ------------------------------------------------------------------------------------- |
+| `x2y` | The `AlignmentArray` object holding the alignment from `x` to `y`. ~~AlignmentArray~~ |
+| `y2x` | The `AlignmentArray` object holding the alignment from `y` to `x`. ~~AlignmentArray~~ |
@@ -309,13 +315,13 @@ tokenizations add up to the same string. For example, you'll be able to align
> spacy_tokens = ["obama", "'s", "podcast"]
> alignment = Alignment.from_strings(bert_tokens, spacy_tokens)
> a2b = alignment.x2y
-> assert list(a2b.dataXd) == [0, 1, 1, 2]
+> assert list(a2b.data) == [0, 1, 1, 2]
> ```
>
-> If `a2b.dataXd[1] == a2b.dataXd[2] == 1`, that means that `A[1]` (`"'"`) and
+> If `a2b.data[1] == a2b.data[2] == 1`, that means that `A[1]` (`"'"`) and
> `A[2]` (`"s"`) both align to `B[1]` (`"'s"`).
-### Alignment.from_strings {#classmethod tag="function"}
+### Alignment.from_strings {id="classmethod",tag="function"}
| Name | Description |
| ----------- | ------------------------------------------------------------- |
diff --git a/website/docs/api/index.md b/website/docs/api/index.mdx
similarity index 58%
rename from website/docs/api/index.md
rename to website/docs/api/index.mdx
index a9dc408f6..6c6e1fff4 100644
--- a/website/docs/api/index.md
+++ b/website/docs/api/index.mdx
@@ -3,6 +3,4 @@ title: Library Architecture
next: /api/architectures
---
-import Architecture101 from 'usage/101/\_architecture.md'
-
diff --git a/website/docs/api/kb.md b/website/docs/api/inmemorylookupkb.mdx
similarity index 56%
rename from website/docs/api/kb.md
rename to website/docs/api/inmemorylookupkb.mdx
index e7a8fcd6f..c24fe78d6 100644
--- a/website/docs/api/kb.md
+++ b/website/docs/api/inmemorylookupkb.mdx
@@ -1,30 +1,29 @@
---
-title: KnowledgeBase
+title: InMemoryLookupKB
teaser:
- A storage class for entities and aliases of a specific knowledge base
- (ontology)
+ The default implementation of the KnowledgeBase interface. Stores all
+ information in-memory.
tag: class
-source: spacy/kb.pyx
-new: 2.2
+source: spacy/kb/kb_in_memory.pyx
+version: 3.5
---
-The `KnowledgeBase` object provides a method to generate
-[`Candidate`](/api/kb/#candidate) objects, which are plausible external
-identifiers given a certain textual mention. Each such `Candidate` holds
-information from the relevant KB entities, such as its frequency in text and
-possible aliases. Each entity in the knowledge base also has a pretrained entity
-vector of a fixed size.
+The `InMemoryLookupKB` class inherits from [`KnowledgeBase`](/api/kb) and
+implements all of its methods. It stores all KB data in-memory and generates
+[`Candidate`](/api/kb#candidate) objects by exactly matching mentions with
+entity names. It's highly optimized for both a low memory footprint and speed of
+retrieval.
-## KnowledgeBase.\_\_init\_\_ {#init tag="method"}
+## InMemoryLookupKB.\_\_init\_\_ {id="init",tag="method"}
Create the knowledge base.
> #### Example
>
> ```python
-> from spacy.kb import KnowledgeBase
+> from spacy.kb import InMemoryLookupKB
> vocab = nlp.vocab
-> kb = KnowledgeBase(vocab=vocab, entity_vector_length=64)
+> kb = InMemoryLookupKB(vocab=vocab, entity_vector_length=64)
> ```
| Name | Description |
@@ -32,7 +31,7 @@ Create the knowledge base.
| `vocab` | The shared vocabulary. ~~Vocab~~ |
| `entity_vector_length` | Length of the fixed-size entity vectors. ~~int~~ |
-## KnowledgeBase.entity_vector_length {#entity_vector_length tag="property"}
+## InMemoryLookupKB.entity_vector_length {id="entity_vector_length",tag="property"}
The length of the fixed-size entity vectors in the knowledge base.
@@ -40,11 +39,11 @@ The length of the fixed-size entity vectors in the knowledge base.
| ----------- | ------------------------------------------------ |
| **RETURNS** | Length of the fixed-size entity vectors. ~~int~~ |
-## KnowledgeBase.add_entity {#add_entity tag="method"}
+## InMemoryLookupKB.add_entity {id="add_entity",tag="method"}
Add an entity to the knowledge base, specifying its corpus frequency and entity
vector, which should be of length
-[`entity_vector_length`](/api/kb#entity_vector_length).
+[`entity_vector_length`](/api/inmemorylookupkb#entity_vector_length).
> #### Example
>
@@ -59,7 +58,7 @@ vector, which should be of length
| `freq` | The frequency of the entity in a typical corpus. ~~float~~ |
| `entity_vector` | The pretrained vector of the entity. ~~numpy.ndarray~~ |
-## KnowledgeBase.set_entities {#set_entities tag="method"}
+## InMemoryLookupKB.set_entities {id="set_entities",tag="method"}
Define the full list of entities in the knowledge base, specifying the corpus
frequency and entity vector for each entity.
@@ -76,13 +75,15 @@ frequency and entity vector for each entity.
| `freq_list` | List of entity frequencies. ~~Iterable[int]~~ |
| `vector_list` | List of entity vectors. ~~Iterable[numpy.ndarray]~~ |
-## KnowledgeBase.add_alias {#add_alias tag="method"}
+## InMemoryLookupKB.add_alias {id="add_alias",tag="method"}
Add an alias or mention to the knowledge base, specifying its potential KB
identifiers and their prior probabilities. The entity identifiers should refer
-to entities previously added with [`add_entity`](/api/kb#add_entity) or
-[`set_entities`](/api/kb#set_entities). The sum of the prior probabilities
-should not exceed 1. Note that an empty string can not be used as alias.
+to entities previously added with
+[`add_entity`](/api/inmemorylookupkb#add_entity) or
+[`set_entities`](/api/inmemorylookupkb#set_entities). The sum of the prior
+probabilities should not exceed 1. Note that an empty string can not be used as
+alias.
> #### Example
>
@@ -96,7 +97,7 @@ should not exceed 1. Note that an empty string can not be used as alias.
| `entities` | The potential entities that the alias may refer to. ~~Iterable[Union[str, int]]~~ |
| `probabilities` | The prior probabilities of each entity. ~~Iterable[float]~~ |
-## KnowledgeBase.\_\_len\_\_ {#len tag="method"}
+## InMemoryLookupKB.\_\_len\_\_ {id="len",tag="method"}
Get the total number of entities in the knowledge base.
@@ -110,7 +111,7 @@ Get the total number of entities in the knowledge base.
| ----------- | ----------------------------------------------------- |
| **RETURNS** | The number of entities in the knowledge base. ~~int~~ |
-## KnowledgeBase.get_entity_strings {#get_entity_strings tag="method"}
+## InMemoryLookupKB.get_entity_strings {id="get_entity_strings",tag="method"}
Get a list of all entity IDs in the knowledge base.
@@ -124,7 +125,7 @@ Get a list of all entity IDs in the knowledge base.
| ----------- | --------------------------------------------------------- |
| **RETURNS** | The list of entities in the knowledge base. ~~List[str]~~ |
-## KnowledgeBase.get_size_aliases {#get_size_aliases tag="method"}
+## InMemoryLookupKB.get_size_aliases {id="get_size_aliases",tag="method"}
Get the total number of aliases in the knowledge base.
@@ -138,7 +139,7 @@ Get the total number of aliases in the knowledge base.
| ----------- | ---------------------------------------------------- |
| **RETURNS** | The number of aliases in the knowledge base. ~~int~~ |
-## KnowledgeBase.get_alias_strings {#get_alias_strings tag="method"}
+## InMemoryLookupKB.get_alias_strings {id="get_alias_strings",tag="method"}
Get a list of all aliases in the knowledge base.
@@ -152,10 +153,56 @@ Get a list of all aliases in the knowledge base.
| ----------- | -------------------------------------------------------- |
| **RETURNS** | The list of aliases in the knowledge base. ~~List[str]~~ |
-## KnowledgeBase.get_alias_candidates {#get_alias_candidates tag="method"}
+## InMemoryLookupKB.get_candidates {id="get_candidates",tag="method"}
Given a certain textual mention as input, retrieve a list of candidate entities
-of type [`Candidate`](/api/kb/#candidate).
+of type [`Candidate`](/api/kb#candidate). Wraps
+[`get_alias_candidates()`](/api/inmemorylookupkb#get_alias_candidates).
+
+> #### Example
+>
+> ```python
+> from spacy.lang.en import English
+> nlp = English()
+> doc = nlp("Douglas Adams wrote 'The Hitchhiker's Guide to the Galaxy'.")
+> candidates = kb.get_candidates(doc[0:2])
+> ```
+
+| Name | Description |
+| ----------- | -------------------------------------------------------------------- |
+| `mention` | The textual mention or alias. ~~Span~~ |
+| **RETURNS** | An iterable of relevant `Candidate` objects. ~~Iterable[Candidate]~~ |
+
+## InMemoryLookupKB.get_candidates_batch {id="get_candidates_batch",tag="method"}
+
+Same as [`get_candidates()`](/api/inmemorylookupkb#get_candidates), but for an
+arbitrary number of mentions. The [`EntityLinker`](/api/entitylinker) component
+will call `get_candidates_batch()` instead of `get_candidates()`, if the config
+parameter `candidates_batch_size` is greater or equal than 1.
+
+The default implementation of `get_candidates_batch()` executes
+`get_candidates()` in a loop. We recommend implementing a more efficient way to
+retrieve candidates for multiple mentions at once, if performance is of concern
+to you.
+
+> #### Example
+>
+> ```python
+> from spacy.lang.en import English
+> nlp = English()
+> doc = nlp("Douglas Adams wrote 'The Hitchhiker's Guide to the Galaxy'.")
+> candidates = kb.get_candidates((doc[0:2], doc[3:]))
+> ```
+
+| Name | Description |
+| ----------- | -------------------------------------------------------------------------------------------- |
+| `mentions` | The textual mention or alias. ~~Iterable[Span]~~ |
+| **RETURNS** | An iterable of iterable with relevant `Candidate` objects. ~~Iterable[Iterable[Candidate]]~~ |
+
+## InMemoryLookupKB.get_alias_candidates {id="get_alias_candidates",tag="method"}
+
+Given a certain textual mention as input, retrieve a list of candidate entities
+of type [`Candidate`](/api/kb#candidate).
> #### Example
>
@@ -168,7 +215,7 @@ of type [`Candidate`](/api/kb/#candidate).
| `alias` | The textual mention or alias. ~~str~~ |
| **RETURNS** | The list of relevant `Candidate` objects. ~~List[Candidate]~~ |
-## KnowledgeBase.get_vector {#get_vector tag="method"}
+## InMemoryLookupKB.get_vector {id="get_vector",tag="method"}
Given a certain entity ID, retrieve its pretrained entity vector.
@@ -183,7 +230,27 @@ Given a certain entity ID, retrieve its pretrained entity vector.
| `entity` | The entity ID. ~~str~~ |
| **RETURNS** | The entity vector. ~~numpy.ndarray~~ |
-## KnowledgeBase.get_prior_prob {#get_prior_prob tag="method"}
+## InMemoryLookupKB.get_vectors {id="get_vectors",tag="method"}
+
+Same as [`get_vector()`](/api/inmemorylookupkb#get_vector), but for an arbitrary
+number of entity IDs.
+
+The default implementation of `get_vectors()` executes `get_vector()` in a loop.
+We recommend implementing a more efficient way to retrieve vectors for multiple
+entities at once, if performance is of concern to you.
+
+> #### Example
+>
+> ```python
+> vectors = kb.get_vectors(("Q42", "Q3107329"))
+> ```
+
+| Name | Description |
+| ----------- | --------------------------------------------------------- |
+| `entities` | The entity IDs. ~~Iterable[str]~~ |
+| **RETURNS** | The entity vectors. ~~Iterable[Iterable[numpy.ndarray]]~~ |
+
+## InMemoryLookupKB.get_prior_prob {id="get_prior_prob",tag="method"}
Given a certain entity ID and a certain textual mention, retrieve the prior
probability of the fact that the mention links to the entity ID.
@@ -200,21 +267,22 @@ probability of the fact that the mention links to the entity ID.
| `alias` | The textual mention or alias. ~~str~~ |
| **RETURNS** | The prior probability of the `alias` referring to the `entity`. ~~float~~ |
-## KnowledgeBase.to_disk {#to_disk tag="method"}
+## InMemoryLookupKB.to_disk {id="to_disk",tag="method"}
Save the current state of the knowledge base to a directory.
> #### Example
>
> ```python
-> kb.to_disk(loc)
+> kb.to_disk(path)
> ```
-| Name | Description |
-| ----- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `loc` | 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]~~ |
+| 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]~~ |
+| `exclude` | List of components to exclude. ~~Iterable[str]~~ |
-## KnowledgeBase.from_disk {#from_disk tag="method"}
+## InMemoryLookupKB.from_disk {id="from_disk",tag="method"}
Restore the state of the knowledge base from a given directory. Note that the
[`Vocab`](/api/vocab) should also be the same as the one used to create the KB.
@@ -222,55 +290,14 @@ Restore the state of the knowledge base from a given directory. Note that the
> #### Example
>
> ```python
-> from spacy.kb import KnowledgeBase
> from spacy.vocab import Vocab
> vocab = Vocab().from_disk("/path/to/vocab")
-> kb = KnowledgeBase(vocab=vocab, entity_vector_length=64)
+> kb = FullyImplementedKB(vocab=vocab, entity_vector_length=64)
> kb.from_disk("/path/to/kb")
> ```
| Name | Description |
| ----------- | ----------------------------------------------------------------------------------------------- |
| `loc` | A path to a directory. Paths may be either strings or `Path`-like objects. ~~Union[str, Path]~~ |
+| `exclude` | List of components to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The modified `KnowledgeBase` object. ~~KnowledgeBase~~ |
-
-## Candidate {#candidate tag="class"}
-
-A `Candidate` object refers to a textual mention (alias) that may or may not be
-resolved to a specific entity from a `KnowledgeBase`. This will be used as input
-for the entity linking algorithm which will disambiguate the various candidates
-to the correct one. Each candidate `(alias, entity)` pair is assigned to a
-certain prior probability.
-
-### Candidate.\_\_init\_\_ {#candidate-init tag="method"}
-
-Construct a `Candidate` object. Usually this constructor is not called directly,
-but instead these objects are returned by the `get_candidates` method of the
-[`entity_linker`](/api/entitylinker) pipe.
-
-> #### Example
->
-> ```python
-> from spacy.kb import Candidate
-> candidate = Candidate(kb, entity_hash, entity_freq, entity_vector, alias_hash, prior_prob)
-> ```
-
-| Name | Description |
-| ------------- | ------------------------------------------------------------------------- |
-| `kb` | The knowledge base that defined this candidate. ~~KnowledgeBase~~ |
-| `entity_hash` | The hash of the entity's KB ID. ~~int~~ |
-| `entity_freq` | The entity frequency as recorded in the KB. ~~float~~ |
-| `alias_hash` | The hash of the textual mention or alias. ~~int~~ |
-| `prior_prob` | The prior probability of the `alias` referring to the `entity`. ~~float~~ |
-
-## Candidate attributes {#candidate-attributes}
-
-| Name | Description |
-| --------------- | ------------------------------------------------------------------------ |
-| `entity` | The entity's unique KB identifier. ~~int~~ |
-| `entity_` | The entity's unique KB identifier. ~~str~~ |
-| `alias` | The alias or textual mention. ~~int~~ |
-| `alias_` | The alias or textual mention. ~~str~~ |
-| `prior_prob` | The prior probability of the `alias` referring to the `entity`. ~~long~~ |
-| `entity_freq` | The frequency of the entity in a typical corpus. ~~long~~ |
-| `entity_vector` | The pretrained vector of the entity. ~~numpy.ndarray~~ |
diff --git a/website/docs/api/kb.mdx b/website/docs/api/kb.mdx
new file mode 100644
index 000000000..2b0d4d9d6
--- /dev/null
+++ b/website/docs/api/kb.mdx
@@ -0,0 +1,232 @@
+---
+title: KnowledgeBase
+teaser:
+ A storage class for entities and aliases of a specific knowledge base
+ (ontology)
+tag: class
+source: spacy/kb/kb.pyx
+version: 2.2
+---
+
+The `KnowledgeBase` object is an abstract class providing a method to generate
+[`Candidate`](/api/kb#candidate) objects, which are plausible external
+identifiers given a certain textual mention. Each such `Candidate` holds
+information from the relevant KB entities, such as its frequency in text and
+possible aliases. Each entity in the knowledge base also has a pretrained entity
+vector of a fixed size.
+
+Beyond that, `KnowledgeBase` classes have to implement a number of utility
+functions called by the [`EntityLinker`](/api/entitylinker) component.
+
+
+
+This class was not abstract up to spaCy version 3.5. The `KnowledgeBase`
+implementation up to that point is available as
+[`InMemoryLookupKB`](/api/inmemorylookupkb) from 3.5 onwards.
+
+
+
+## KnowledgeBase.\_\_init\_\_ {id="init",tag="method"}
+
+`KnowledgeBase` is an abstract class and cannot be instantiated. Its child
+classes should call `__init__()` to set up some necessary attributes.
+
+> #### Example
+>
+> ```python
+> from spacy.kb import KnowledgeBase
+> from spacy.vocab import Vocab
+>
+> class FullyImplementedKB(KnowledgeBase):
+> def __init__(self, vocab: Vocab, entity_vector_length: int):
+> super().__init__(vocab, entity_vector_length)
+> ...
+> vocab = nlp.vocab
+> kb = FullyImplementedKB(vocab=vocab, entity_vector_length=64)
+> ```
+
+| Name | Description |
+| ---------------------- | ------------------------------------------------ |
+| `vocab` | The shared vocabulary. ~~Vocab~~ |
+| `entity_vector_length` | Length of the fixed-size entity vectors. ~~int~~ |
+
+## KnowledgeBase.entity_vector_length {id="entity_vector_length",tag="property"}
+
+The length of the fixed-size entity vectors in the knowledge base.
+
+| Name | Description |
+| ----------- | ------------------------------------------------ |
+| **RETURNS** | Length of the fixed-size entity vectors. ~~int~~ |
+
+## KnowledgeBase.get_candidates {id="get_candidates",tag="method"}
+
+Given a certain textual mention as input, retrieve a list of candidate entities
+of type [`Candidate`](/api/kb#candidate).
+
+> #### Example
+>
+> ```python
+> from spacy.lang.en import English
+> nlp = English()
+> doc = nlp("Douglas Adams wrote 'The Hitchhiker's Guide to the Galaxy'.")
+> candidates = kb.get_candidates(doc[0:2])
+> ```
+
+| Name | Description |
+| ----------- | -------------------------------------------------------------------- |
+| `mention` | The textual mention or alias. ~~Span~~ |
+| **RETURNS** | An iterable of relevant `Candidate` objects. ~~Iterable[Candidate]~~ |
+
+## KnowledgeBase.get_candidates_batch {id="get_candidates_batch",tag="method"}
+
+Same as [`get_candidates()`](/api/kb#get_candidates), but for an arbitrary
+number of mentions. The [`EntityLinker`](/api/entitylinker) component will call
+`get_candidates_batch()` instead of `get_candidates()`, if the config parameter
+`candidates_batch_size` is greater or equal than 1.
+
+The default implementation of `get_candidates_batch()` executes
+`get_candidates()` in a loop. We recommend implementing a more efficient way to
+retrieve candidates for multiple mentions at once, if performance is of concern
+to you.
+
+> #### Example
+>
+> ```python
+> from spacy.lang.en import English
+> nlp = English()
+> doc = nlp("Douglas Adams wrote 'The Hitchhiker's Guide to the Galaxy'.")
+> candidates = kb.get_candidates((doc[0:2], doc[3:]))
+> ```
+
+| Name | Description |
+| ----------- | -------------------------------------------------------------------------------------------- |
+| `mentions` | The textual mention or alias. ~~Iterable[Span]~~ |
+| **RETURNS** | An iterable of iterable with relevant `Candidate` objects. ~~Iterable[Iterable[Candidate]]~~ |
+
+## KnowledgeBase.get_alias_candidates {id="get_alias_candidates",tag="method"}
+
+
+ This method is _not_ available from spaCy 3.5 onwards.
+
+
+From spaCy 3.5 on `KnowledgeBase` is an abstract class (with
+[`InMemoryLookupKB`](/api/inmemorylookupkb) being a drop-in replacement) to
+allow more flexibility in customizing knowledge bases. Some of its methods were
+moved to [`InMemoryLookupKB`](/api/inmemorylookupkb) during this refactoring,
+one of those being `get_alias_candidates()`. This method is now available as
+[`InMemoryLookupKB.get_alias_candidates()`](/api/inmemorylookupkb#get_alias_candidates).
+Note:
+[`InMemoryLookupKB.get_candidates()`](/api/inmemorylookupkb#get_candidates)
+defaults to
+[`InMemoryLookupKB.get_alias_candidates()`](/api/inmemorylookupkb#get_alias_candidates).
+
+## KnowledgeBase.get_vector {id="get_vector",tag="method"}
+
+Given a certain entity ID, retrieve its pretrained entity vector.
+
+> #### Example
+>
+> ```python
+> vector = kb.get_vector("Q42")
+> ```
+
+| Name | Description |
+| ----------- | -------------------------------------- |
+| `entity` | The entity ID. ~~str~~ |
+| **RETURNS** | The entity vector. ~~Iterable[float]~~ |
+
+## KnowledgeBase.get_vectors {id="get_vectors",tag="method"}
+
+Same as [`get_vector()`](/api/kb#get_vector), but for an arbitrary number of
+entity IDs.
+
+The default implementation of `get_vectors()` executes `get_vector()` in a loop.
+We recommend implementing a more efficient way to retrieve vectors for multiple
+entities at once, if performance is of concern to you.
+
+> #### Example
+>
+> ```python
+> vectors = kb.get_vectors(("Q42", "Q3107329"))
+> ```
+
+| Name | Description |
+| ----------- | --------------------------------------------------------- |
+| `entities` | The entity IDs. ~~Iterable[str]~~ |
+| **RETURNS** | The entity vectors. ~~Iterable[Iterable[numpy.ndarray]]~~ |
+
+## KnowledgeBase.to_disk {id="to_disk",tag="method"}
+
+Save the current state of the knowledge base to a directory.
+
+> #### Example
+>
+> ```python
+> kb.to_disk(path)
+> ```
+
+| 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]~~ |
+| `exclude` | List of components to exclude. ~~Iterable[str]~~ |
+
+## KnowledgeBase.from_disk {id="from_disk",tag="method"}
+
+Restore the state of the knowledge base from a given directory. Note that the
+[`Vocab`](/api/vocab) should also be the same as the one used to create the KB.
+
+> #### Example
+>
+> ```python
+> from spacy.vocab import Vocab
+> vocab = Vocab().from_disk("/path/to/vocab")
+> kb = FullyImplementedKB(vocab=vocab, entity_vector_length=64)
+> kb.from_disk("/path/to/kb")
+> ```
+
+| Name | Description |
+| ----------- | ----------------------------------------------------------------------------------------------- |
+| `loc` | A path to a directory. Paths may be either strings or `Path`-like objects. ~~Union[str, Path]~~ |
+| `exclude` | List of components to exclude. ~~Iterable[str]~~ |
+| **RETURNS** | The modified `KnowledgeBase` object. ~~KnowledgeBase~~ |
+
+## Candidate {id="candidate",tag="class"}
+
+A `Candidate` object refers to a textual mention (alias) that may or may not be
+resolved to a specific entity from a `KnowledgeBase`. This will be used as input
+for the entity linking algorithm which will disambiguate the various candidates
+to the correct one. Each candidate `(alias, entity)` pair is assigned to a
+certain prior probability.
+
+### Candidate.\_\_init\_\_ {id="candidate-init",tag="method"}
+
+Construct a `Candidate` object. Usually this constructor is not called directly,
+but instead these objects are returned by the `get_candidates` method of the
+[`entity_linker`](/api/entitylinker) pipe.
+
+> #### Example
+>
+> ```python
+> from spacy.kb import Candidate
+> candidate = Candidate(kb, entity_hash, entity_freq, entity_vector, alias_hash, prior_prob)
+> ```
+
+| Name | Description |
+| ------------- | ------------------------------------------------------------------------- |
+| `kb` | The knowledge base that defined this candidate. ~~KnowledgeBase~~ |
+| `entity_hash` | The hash of the entity's KB ID. ~~int~~ |
+| `entity_freq` | The entity frequency as recorded in the KB. ~~float~~ |
+| `alias_hash` | The hash of the textual mention or alias. ~~int~~ |
+| `prior_prob` | The prior probability of the `alias` referring to the `entity`. ~~float~~ |
+
+## Candidate attributes {id="candidate-attributes"}
+
+| Name | Description |
+| --------------- | ------------------------------------------------------------------------ |
+| `entity` | The entity's unique KB identifier. ~~int~~ |
+| `entity_` | The entity's unique KB identifier. ~~str~~ |
+| `alias` | The alias or textual mention. ~~int~~ |
+| `alias_` | The alias or textual mention. ~~str~~ |
+| `prior_prob` | The prior probability of the `alias` referring to the `entity`. ~~long~~ |
+| `entity_freq` | The frequency of the entity in a typical corpus. ~~long~~ |
+| `entity_vector` | The pretrained vector of the entity. ~~numpy.ndarray~~ |
diff --git a/website/docs/api/language.md b/website/docs/api/language.mdx
similarity index 87%
rename from website/docs/api/language.md
rename to website/docs/api/language.mdx
index 8d7686243..93ddd79a2 100644
--- a/website/docs/api/language.md
+++ b/website/docs/api/language.mdx
@@ -15,7 +15,7 @@ the tagger or parser that are called on a document in order. You can also add
your own processing pipeline components that take a `Doc` object, modify it and
return it.
-## Language.\_\_init\_\_ {#init tag="method"}
+## Language.\_\_init\_\_ {id="init",tag="method"}
Initialize a `Language` object. Note that the `meta` is only used for meta
information in [`Language.meta`](/api/language#meta) and not to configure the
@@ -44,7 +44,7 @@ information in [`Language.meta`](/api/language#meta) and not to configure the
| `create_tokenizer` | Optional function that receives the `nlp` object and returns a tokenizer. ~~Callable[[Language], Callable[[str], Doc]]~~ |
| `batch_size` | Default batch size for [`pipe`](#pipe) and [`evaluate`](#evaluate). Defaults to `1000`. ~~int~~ |
-## Language.from_config {#from_config tag="classmethod" new="3"}
+## Language.from_config {id="from_config",tag="classmethod",version="3"}
Create a `Language` object from a loaded config. Will set up the tokenizer and
language data, add pipeline components based on the pipeline and add pipeline
@@ -63,19 +63,20 @@ spaCy loads a model under the hood based on its
> nlp = Language.from_config(config)
> ```
-| Name | Description |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `config` | The loaded config. ~~Union[Dict[str, Any], Config]~~ |
-| _keyword-only_ | |
-| `vocab` | A `Vocab` object. If `True`, a vocab is created using the default language data settings. ~~Vocab~~ |
-| `disable` | Names of pipeline components to [disable](/usage/processing-pipelines#disabling). Disabled pipes will be loaded but they won't be run unless you explicitly enable them by calling [`nlp.enable_pipe`](/api/language#enable_pipe). ~~List[str]~~ |
-| `exclude` | Names of pipeline components to [exclude](/usage/processing-pipelines#disabling). Excluded components won't be loaded. ~~List[str]~~ |
-| `meta` | [Meta data](/api/data-formats#meta) overrides. ~~Dict[str, Any]~~ |
-| `auto_fill` | Whether to automatically fill in missing values in the config, based on defaults and function argument annotations. Defaults to `True`. ~~bool~~ |
-| `validate` | Whether to validate the component config and arguments against the types expected by the factory. Defaults to `True`. ~~bool~~ |
-| **RETURNS** | The initialized object. ~~Language~~ |
+| Name | Description |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `config` | The loaded config. ~~Union[Dict[str, Any], Config]~~ |
+| _keyword-only_ | |
+| `vocab` | A `Vocab` object. If `True`, a vocab is created using the default language data settings. ~~Vocab~~ |
+| `disable` | Name(s) of pipeline component(s) to [disable](/usage/processing-pipelines#disabling). Disabled pipes will be loaded but they won't be run unless you explicitly enable them by calling [nlp.enable_pipe](/api/language#enable_pipe). Is merged with the config entry `nlp.disabled`. ~~Union[str, Iterable[str]]~~ |
+| `enable` 3.4 | Name(s) of pipeline component(s) to [enable](/usage/processing-pipelines#disabling). All other pipes will be disabled, but can be enabled again using [nlp.enable_pipe](/api/language#enable_pipe). ~~Union[str, Iterable[str]]~~ |
+| `exclude` | Name(s) of pipeline component(s) to [exclude](/usage/processing-pipelines#disabling). Excluded components won't be loaded. ~~Union[str, Iterable[str]]~~ |
+| `meta` | [Meta data](/api/data-formats#meta) overrides. ~~Dict[str, Any]~~ |
+| `auto_fill` | Whether to automatically fill in missing values in the config, based on defaults and function argument annotations. Defaults to `True`. ~~bool~~ |
+| `validate` | Whether to validate the component config and arguments against the types expected by the factory. Defaults to `True`. ~~bool~~ |
+| **RETURNS** | The initialized object. ~~Language~~ |
-## Language.component {#component tag="classmethod" new="3"}
+## Language.component {id="component",tag="classmethod",version="3"}
Register a custom pipeline component under a given name. This allows
initializing the component by name using
@@ -111,7 +112,7 @@ decorator. For more details and examples, see the
| `retokenizes` | Whether the component changes tokenization. Used for [pipe analysis](/usage/processing-pipelines#analysis). ~~bool~~ |
| `func` | Optional function if not used as a decorator. ~~Optional[Callable[[Doc], Doc]]~~ |
-## Language.factory {#factory tag="classmethod"}
+## Language.factory {id="factory",tag="classmethod"}
Register a custom pipeline component factory under a given name. This allows
initializing the component by name using
@@ -158,11 +159,14 @@ examples, see the
| `default_score_weights` | The scores to report during training, and their default weight towards the final score used to select the best model. Weights should sum to `1.0` per component and will be combined and normalized for the whole pipeline. If a weight is set to `None`, the score will not be logged or weighted. ~~Dict[str, Optional[float]]~~ |
| `func` | Optional function if not used as a decorator. ~~Optional[Callable[[...], Callable[[Doc], Doc]]]~~ |
-## Language.\_\_call\_\_ {#call tag="method"}
+## Language.\_\_call\_\_ {id="call",tag="method"}
Apply the pipeline to some text. The text can span multiple sentences, and can
contain arbitrary whitespace. Alignment into the original string is preserved.
+Instead of text, a `Doc` can be passed as input, in which case tokenization is
+skipped, but the rest of the pipeline is run.
+
> #### Example
>
> ```python
@@ -172,17 +176,20 @@ contain arbitrary whitespace. Alignment into the original string is preserved.
| Name | Description |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `text` | The text to be processed. ~~str~~ |
+| `text` | The text to be processed, or a Doc. ~~Union[str, Doc]~~ |
| _keyword-only_ | |
| `disable` | Names of pipeline components to [disable](/usage/processing-pipelines#disabling). ~~List[str]~~ |
| `component_cfg` | Optional dictionary of keyword arguments for components, keyed by component names. Defaults to `None`. ~~Optional[Dict[str, Dict[str, Any]]]~~ |
| **RETURNS** | A container for accessing the annotations. ~~Doc~~ |
-## Language.pipe {#pipe tag="method"}
+## Language.pipe {id="pipe",tag="method"}
Process texts as a stream, and yield `Doc` objects in order. This is usually
more efficient than processing texts one-by-one.
+Instead of text, a `Doc` object can be passed as input. In this case
+tokenization is skipped but the rest of the pipeline is run.
+
> #### Example
>
> ```python
@@ -191,18 +198,18 @@ more efficient than processing texts one-by-one.
> assert doc.has_annotation("DEP")
> ```
-| Name | Description |
-| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `texts` | A sequence of strings. ~~Iterable[str]~~ |
-| _keyword-only_ | |
-| `as_tuples` | If set to `True`, inputs should be a sequence of `(text, context)` tuples. Output will then be a sequence of `(doc, context)` tuples. Defaults to `False`. ~~bool~~ |
-| `batch_size` | The number of texts to buffer. ~~Optional[int]~~ |
-| `disable` | Names of pipeline components to [disable](/usage/processing-pipelines#disabling). ~~List[str]~~ |
-| `component_cfg` | Optional dictionary of keyword arguments for components, keyed by component names. Defaults to `None`. ~~Optional[Dict[str, Dict[str, Any]]]~~ |
-| `n_process` 2.2.2 | Number of processors to use. Defaults to `1`. ~~int~~ |
-| **YIELDS** | Documents in the order of the original text. ~~Doc~~ |
+| Name | Description |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `texts` | A sequence of strings (or `Doc` objects). ~~Iterable[Union[str, Doc]]~~ |
+| _keyword-only_ | |
+| `as_tuples` | If set to `True`, inputs should be a sequence of `(text, context)` tuples. Output will then be a sequence of `(doc, context)` tuples. Defaults to `False`. ~~bool~~ |
+| `batch_size` | The number of texts to buffer. ~~Optional[int]~~ |
+| `disable` | Names of pipeline components to [disable](/usage/processing-pipelines#disabling). ~~List[str]~~ |
+| `component_cfg` | Optional dictionary of keyword arguments for components, keyed by component names. Defaults to `None`. ~~Optional[Dict[str, Dict[str, Any]]]~~ |
+| `n_process` | Number of processors to use. Defaults to `1`. ~~int~~ |
+| **YIELDS** | Documents in the order of the original text. ~~Doc~~ |
-## Language.set_error_handler {#set_error_handler tag="method" new="3"}
+## Language.set_error_handler {id="set_error_handler",tag="method",version="3"}
Define a callback that will be invoked when an error is thrown during processing
of one or more documents. Specifically, this function will call
@@ -224,7 +231,7 @@ being processed, and the original error.
| --------------- | -------------------------------------------------------------------------------------------------------------- |
| `error_handler` | A function that performs custom error handling. ~~Callable[[str, Callable[[Doc], Doc], List[Doc], Exception]~~ |
-## Language.initialize {#initialize tag="method" new="3"}
+## Language.initialize {id="initialize",tag="method",version="3"}
Initialize the pipeline for training and return an
[`Optimizer`](https://thinc.ai/docs/api-optimizers). Under the hood, it uses the
@@ -275,7 +282,7 @@ objects.
| `sgd` | An optimizer. Will be created via [`create_optimizer`](#create_optimizer) if not set. ~~Optional[Optimizer]~~ |
| **RETURNS** | The optimizer. ~~Optimizer~~ |
-## Language.resume_training {#resume_training tag="method,experimental" new="3"}
+## Language.resume_training {id="resume_training",tag="method,experimental",version="3"}
Continue training a trained pipeline. Create and return an optimizer, and
initialize "rehearsal" for any pipeline component that has a `rehearse` method.
@@ -297,7 +304,7 @@ a batch of [Example](/api/example) objects.
| `sgd` | An optimizer. Will be created via [`create_optimizer`](#create_optimizer) if not set. ~~Optional[Optimizer]~~ |
| **RETURNS** | The optimizer. ~~Optimizer~~ |
-## Language.update {#update tag="method"}
+## Language.update {id="update",tag="method"}
Update the models in the pipeline.
@@ -335,7 +342,7 @@ and custom registered functions if needed. See the
| `component_cfg` | Optional dictionary of keyword arguments for components, keyed by component names. Defaults to `None`. ~~Optional[Dict[str, Dict[str, Any]]]~~ |
| **RETURNS** | The updated `losses` dictionary. ~~Dict[str, float]~~ |
-## Language.rehearse {#rehearse tag="method,experimental" new="3"}
+## Language.rehearse {id="rehearse",tag="method,experimental",version="3"}
Perform a "rehearsal" update from a batch of data. Rehearsal updates teach the
current model to make predictions similar to an initial model, to try to address
@@ -357,7 +364,7 @@ the "catastrophic forgetting" problem. This feature is experimental.
| `losses` | Dictionary to update with the loss, keyed by pipeline component. ~~Optional[Dict[str, float]]~~ |
| **RETURNS** | The updated `losses` dictionary. ~~Dict[str, float]~~ |
-## Language.evaluate {#evaluate tag="method"}
+## Language.evaluate {id="evaluate",tag="method"}
Evaluate a pipeline's components.
@@ -385,7 +392,7 @@ objects instead of tuples of `Doc` and `GoldParse` objects.
| `scorer_cfg` | Optional dictionary of keyword arguments for the `Scorer`. Defaults to `None`. ~~Optional[Dict[str, Any]]~~ |
| **RETURNS** | A dictionary of evaluation scores. ~~Dict[str, Union[float, Dict[str, float]]]~~ |
-## Language.use_params {#use_params tag="contextmanager, method"}
+## Language.use_params {id="use_params",tag="contextmanager, method"}
Replace weights of models in the pipeline with those provided in the params
dictionary. Can be used as a context manager, in which case, models go back to
@@ -402,7 +409,7 @@ their original weights after the block.
| -------- | ------------------------------------------------------ |
| `params` | A dictionary of parameters keyed by model ID. ~~dict~~ |
-## Language.add_pipe {#add_pipe tag="method" new="2"}
+## Language.add_pipe {id="add_pipe",tag="method",version="2"}
Add a component to the processing pipeline. Expects a name that maps to a
component factory registered using
@@ -451,7 +458,7 @@ component, adds it to the pipeline and returns it.
| `validate` 3 | Whether to validate the component config and arguments against the types expected by the factory. Defaults to `True`. ~~bool~~ |
| **RETURNS** | The pipeline component. ~~Callable[[Doc], Doc]~~ |
-## Language.create_pipe {#create_pipe tag="method" new="2"}
+## Language.create_pipe {id="create_pipe",tag="method",version="2"}
Create a pipeline component from a factory.
@@ -480,7 +487,7 @@ To create a component and add it to the pipeline, you should always use
| `validate` 3 | Whether to validate the component config and arguments against the types expected by the factory. Defaults to `True`. ~~bool~~ |
| **RETURNS** | The pipeline component. ~~Callable[[Doc], Doc]~~ |
-## Language.has_factory {#has_factory tag="classmethod" new="3"}
+## Language.has_factory {id="has_factory",tag="classmethod",version="3"}
Check whether a factory name is registered on the `Language` class or subclass.
Will check for
@@ -507,7 +514,7 @@ the `Language` base class, available to all subclasses.
| `name` | Name of the pipeline factory to check. ~~str~~ |
| **RETURNS** | Whether a factory of that name is registered on the class. ~~bool~~ |
-## Language.has_pipe {#has_pipe tag="method" new="2"}
+## Language.has_pipe {id="has_pipe",tag="method",version="2"}
Check whether a component is present in the pipeline. Equivalent to
`name in nlp.pipe_names`.
@@ -529,7 +536,7 @@ Check whether a component is present in the pipeline. Equivalent to
| `name` | Name of the pipeline component to check. ~~str~~ |
| **RETURNS** | Whether a component of that name exists in the pipeline. ~~bool~~ |
-## Language.get_pipe {#get_pipe tag="method" new="2"}
+## Language.get_pipe {id="get_pipe",tag="method",version="2"}
Get a pipeline component for a given component name.
@@ -545,7 +552,7 @@ Get a pipeline component for a given component name.
| `name` | Name of the pipeline component to get. ~~str~~ |
| **RETURNS** | The pipeline component. ~~Callable[[Doc], Doc]~~ |
-## Language.replace_pipe {#replace_pipe tag="method" new="2"}
+## Language.replace_pipe {id="replace_pipe",tag="method",version="2"}
Replace a component in the pipeline and return the new component.
@@ -573,7 +580,7 @@ and instead expects the **name of a component factory** registered using
| `validate` 3 | Whether to validate the component config and arguments against the types expected by the factory. Defaults to `True`. ~~bool~~ |
| **RETURNS** | The new pipeline component. ~~Callable[[Doc], Doc]~~ |
-## Language.rename_pipe {#rename_pipe tag="method" new="2"}
+## Language.rename_pipe {id="rename_pipe",tag="method",version="2"}
Rename a component in the pipeline. Useful to create custom names for
pre-defined and pre-loaded components. To change the default name of a component
@@ -591,7 +598,7 @@ added to the pipeline, you can also use the `name` argument on
| `old_name` | Name of the component to rename. ~~str~~ |
| `new_name` | New name of the component. ~~str~~ |
-## Language.remove_pipe {#remove_pipe tag="method" new="2"}
+## Language.remove_pipe {id="remove_pipe",tag="method",version="2"}
Remove a component from the pipeline. Returns the removed component name and
component function.
@@ -608,7 +615,7 @@ component function.
| `name` | Name of the component to remove. ~~str~~ |
| **RETURNS** | A `(name, component)` tuple of the removed component. ~~Tuple[str, Callable[[Doc], Doc]]~~ |
-## Language.disable_pipe {#disable_pipe tag="method" new="3"}
+## Language.disable_pipe {id="disable_pipe",tag="method",version="3"}
Temporarily disable a pipeline component so it's not run as part of the
pipeline. Disabled components are listed in
@@ -634,7 +641,7 @@ does nothing.
| ------ | ----------------------------------------- |
| `name` | Name of the component to disable. ~~str~~ |
-## Language.enable_pipe {#enable_pipe tag="method" new="3"}
+## Language.enable_pipe {id="enable_pipe",tag="method",version="3"}
Enable a previously disabled component (e.g. via
[`Language.disable_pipes`](/api/language#disable_pipes)) so it's run as part of
@@ -656,7 +663,7 @@ already enabled, this method does nothing.
| ------ | ---------------------------------------- |
| `name` | Name of the component to enable. ~~str~~ |
-## Language.select_pipes {#select_pipes tag="contextmanager, method" new="3"}
+## Language.select_pipes {id="select_pipes",tag="contextmanager, method",version="3"}
Disable one or more pipeline components. If used as a context manager, the
pipeline will be restored to the initial state at the end of the block.
@@ -695,11 +702,11 @@ As of spaCy v3.0, the `disable_pipes` method has been renamed to `select_pipes`:
| Name | Description |
| -------------- | ------------------------------------------------------------------------------------------------------ |
| _keyword-only_ | |
-| `disable` | Name(s) of pipeline components to disable. ~~Optional[Union[str, Iterable[str]]]~~ |
-| `enable` | Name(s) of pipeline components that will not be disabled. ~~Optional[Union[str, Iterable[str]]]~~ |
+| `disable` | Name(s) of pipeline component(s) to disable. ~~Optional[Union[str, Iterable[str]]]~~ |
+| `enable` | Name(s) of pipeline component(s) that will not be disabled. ~~Optional[Union[str, Iterable[str]]]~~ |
| **RETURNS** | The disabled pipes that can be restored by calling the object's `.restore()` method. ~~DisabledPipes~~ |
-## Language.get_factory_meta {#get_factory_meta tag="classmethod" new="3"}
+## Language.get_factory_meta {id="get_factory_meta",tag="classmethod",version="3"}
Get the factory meta information for a given pipeline component name. Expects
the name of the component **factory**. The factory meta is an instance of the
@@ -721,7 +728,7 @@ information about the component and its default provided by the
| `name` | The factory name. ~~str~~ |
| **RETURNS** | The factory meta. ~~FactoryMeta~~ |
-## Language.get_pipe_meta {#get_pipe_meta tag="method" new="3"}
+## Language.get_pipe_meta {id="get_pipe_meta",tag="method",version="3"}
Get the factory meta information for a given pipeline component name. Expects
the name of the component **instance** in the pipeline. The factory meta is an
@@ -744,7 +751,7 @@ contains the information about the component and its default provided by the
| `name` | The pipeline component name. ~~str~~ |
| **RETURNS** | The factory meta. ~~FactoryMeta~~ |
-## Language.analyze_pipes {#analyze_pipes tag="method" new="3"}
+## Language.analyze_pipes {id="analyze_pipes",tag="method",version="3"}
Analyze the current pipeline components and show a summary of the attributes
they assign and require, and the scores they set. The data is based on the
@@ -773,8 +780,7 @@ doesn't, the pipeline analysis won't catch that.
-```json
-### Structured
+```json {title="Structured"}
{
"summary": {
"tagger": {
@@ -792,7 +798,12 @@ doesn't, the pipeline analysis won't catch that.
},
"problems": {
"tagger": [],
- "entity_linker": ["doc.ents", "doc.sents", "token.ent_iob", "token.ent_type"]
+ "entity_linker": [
+ "doc.ents",
+ "doc.sents",
+ "token.ent_iob",
+ "token.ent_type"
+ ]
},
"attrs": {
"token.ent_iob": { "assigns": [], "requires": ["entity_linker"] },
@@ -833,7 +844,7 @@ token.ent_iob, token.ent_type
| `pretty` | Pretty-print the results as a table. Defaults to `False`. ~~bool~~ |
| **RETURNS** | Dictionary containing the pipe analysis, keyed by `"summary"` (component meta by pipe), `"problems"` (attribute names by pipe) and `"attrs"` (pipes that assign and require an attribute, keyed by attribute). ~~Optional[Dict[str, Any]]~~ |
-## Language.replace_listeners {#replace_listeners tag="method" new="3"}
+## Language.replace_listeners {id="replace_listeners",tag="method",version="3"}
Find [listener layers](/usage/embeddings-transformers#embedding-layers)
(connecting to a shared token-to-vector embedding component) of a given pipeline
@@ -878,7 +889,7 @@ when loading a config with
| `pipe_name` | Name of pipeline component to replace listeners for. ~~str~~ |
| `listeners` | The paths to the listeners, relative to the component config, e.g. `["model.tok2vec"]`. Typically, implementations will only connect to one tok2vec component, `model.tok2vec`, but in theory, custom models can use multiple listeners. The value here can either be an empty list to not replace any listeners, or a _complete_ list of the paths to all listener layers used by the model that should be replaced.~~Iterable[str]~~ |
-## Language.meta {#meta tag="property"}
+## Language.meta {id="meta",tag="property"}
Meta data for the `Language` class, including name, version, data sources,
license, author information and more. If a trained pipeline is loaded, this
@@ -904,7 +915,7 @@ information is expressed in the [`config.cfg`](/api/data-formats#config).
| ----------- | --------------------------------- |
| **RETURNS** | The meta data. ~~Dict[str, Any]~~ |
-## Language.config {#config tag="property" new="3"}
+## Language.config {id="config",tag="property",version="3"}
Export a trainable [`config.cfg`](/api/data-formats#config) for the current
`nlp` object. Includes the current pipeline, all configs used to create the
@@ -925,7 +936,7 @@ subclass of the built-in `dict`. It supports the additional methods `to_disk`
| ----------- | ---------------------- |
| **RETURNS** | The config. ~~Config~~ |
-## Language.to_disk {#to_disk tag="method" new="2"}
+## Language.to_disk {id="to_disk",tag="method",version="2"}
Save the current state to a directory. Under the hood, this method delegates to
the `to_disk` methods of the individual pipeline components, if available. This
@@ -944,7 +955,7 @@ will be saved to disk.
| _keyword-only_ | |
| `exclude` | Names of pipeline components or [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
-## Language.from_disk {#from_disk tag="method" new="2"}
+## Language.from_disk {id="from_disk",tag="method",version="2"}
Loads state from a directory, including all data that was saved with the
`Language` object. Modifies the object in place and returns it.
@@ -977,7 +988,7 @@ you want to load a serialized pipeline from a directory, you should use
| `exclude` | Names of pipeline components or [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The modified `Language` object. ~~Language~~ |
-## Language.to_bytes {#to_bytes tag="method"}
+## Language.to_bytes {id="to_bytes",tag="method"}
Serialize the current state to a binary string.
@@ -993,7 +1004,7 @@ Serialize the current state to a binary string.
| `exclude` | Names of pipeline components or [serialization fields](#serialization-fields) to exclude. ~~iterable~~ |
| **RETURNS** | The serialized form of the `Language` object. ~~bytes~~ |
-## Language.from_bytes {#from_bytes tag="method"}
+## Language.from_bytes {id="from_bytes",tag="method"}
Load state from a binary string. Note that this method is commonly used via the
subclasses like `English` or `German` to make language-specific functionality
@@ -1021,25 +1032,25 @@ details.
| `exclude` | Names of pipeline components or [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The `Language` object. ~~Language~~ |
-## Attributes {#attributes}
+## Attributes {id="attributes"}
-| Name | Description |
-| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `vocab` | A container for the lexical types. ~~Vocab~~ |
-| `tokenizer` | The tokenizer. ~~Tokenizer~~ |
-| `make_doc` | Callable that takes a string and returns a `Doc`. ~~Callable[[str], Doc]~~ |
-| `pipeline` | List of `(name, component)` tuples describing the current processing pipeline, in order. ~~List[Tuple[str, Callable[[Doc], Doc]]]~~ |
-| `pipe_names` 2 | List of pipeline component names, in order. ~~List[str]~~ |
-| `pipe_labels` 2.2 | List of labels set by the pipeline components, if available, keyed by component name. ~~Dict[str, List[str]]~~ |
-| `pipe_factories` 2.2 | Dictionary of pipeline component names, mapped to their factory names. ~~Dict[str, str]~~ |
-| `factories` | All available factory functions, keyed by name. ~~Dict[str, Callable[[...], Callable[[Doc], Doc]]]~~ |
-| `factory_names` 3 | List of all available factory names. ~~List[str]~~ |
-| `components` 3 | List of all available `(name, component)` tuples, including components that are currently disabled. ~~List[Tuple[str, Callable[[Doc], Doc]]]~~ |
-| `component_names` 3 | List of all available component names, including components that are currently disabled. ~~List[str]~~ |
-| `disabled` 3 | Names of components that are currently disabled and don't run as part of the pipeline. ~~List[str]~~ |
-| `path` 2 | Path to the pipeline data directory, if a pipeline is loaded from a path or package. Otherwise `None`. ~~Optional[Path]~~ |
+| Name | Description |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `vocab` | A container for the lexical types. ~~Vocab~~ |
+| `tokenizer` | The tokenizer. ~~Tokenizer~~ |
+| `make_doc` | Callable that takes a string and returns a `Doc`. ~~Callable[[str], Doc]~~ |
+| `pipeline` | List of `(name, component)` tuples describing the current processing pipeline, in order. ~~List[Tuple[str, Callable[[Doc], Doc]]]~~ |
+| `pipe_names` | List of pipeline component names, in order. ~~List[str]~~ |
+| `pipe_labels` | List of labels set by the pipeline components, if available, keyed by component name. ~~Dict[str, List[str]]~~ |
+| `pipe_factories` | Dictionary of pipeline component names, mapped to their factory names. ~~Dict[str, str]~~ |
+| `factories` | All available factory functions, keyed by name. ~~Dict[str, Callable[[...], Callable[[Doc], Doc]]]~~ |
+| `factory_names` 3 | List of all available factory names. ~~List[str]~~ |
+| `components` 3 | List of all available `(name, component)` tuples, including components that are currently disabled. ~~List[Tuple[str, Callable[[Doc], Doc]]]~~ |
+| `component_names` 3 | List of all available component names, including components that are currently disabled. ~~List[str]~~ |
+| `disabled` 3 | Names of components that are currently disabled and don't run as part of the pipeline. ~~List[str]~~ |
+| `path` | Path to the pipeline data directory, if a pipeline is loaded from a path or package. Otherwise `None`. ~~Optional[Path]~~ |
-## Class attributes {#class-attributes}
+## Class attributes {id="class-attributes"}
| Name | Description |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -1047,7 +1058,7 @@ details.
| `lang` | [IETF language tag](https://www.w3.org/International/articles/language-tags/), such as 'en' for English. ~~str~~ |
| `default_config` | Base [config](/usage/training#config) to use for [Language.config](/api/language#config). Defaults to [`default_config.cfg`](%%GITHUB_SPACY/spacy/default_config.cfg). ~~Config~~ |
-## Defaults {#defaults}
+## Defaults {id="defaults"}
The following attributes can be set on the `Language.Defaults` class to
customize the default language data:
@@ -1090,7 +1101,7 @@ customize the default language data:
| `writing_system` | Information about the language's writing system, available via `Vocab.writing_system`. Defaults to: `{"direction": "ltr", "has_case": True, "has_letters": True}.`. **Example:** [`zh/__init__.py`](%%GITHUB_SPACY/spacy/lang/zh/__init__.py) ~~Dict[str, Any]~~ |
| `config` | Default [config](/usage/training#config) added to `nlp.config`. This can include references to custom tokenizers or lemmatizers. **Example:** [`zh/__init__.py`](%%GITHUB_SPACY/spacy/lang/zh/__init__.py) ~~Config~~ |
-## Serialization fields {#serialization-fields}
+## Serialization fields {id="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
@@ -1110,7 +1121,7 @@ serialization by passing in the string names via the `exclude` argument.
| `meta` | The meta data, available as [`Language.meta`](/api/language#meta). |
| ... | String names of pipeline components, e.g. `"ner"`. |
-## FactoryMeta {#factorymeta new="3" tag="dataclass"}
+## FactoryMeta {id="factorymeta",version="3",tag="dataclass"}
The `FactoryMeta` contains the information about the component and its default
provided by the [`@Language.component`](/api/language#component) or
@@ -1123,7 +1134,7 @@ instance and factory instance.
| `factory` | The name of the registered component factory. ~~str~~ |
| `default_config` | The default config, describing the default values of the factory arguments. ~~Dict[str, Any]~~ |
| `assigns` | `Doc` or `Token` attributes assigned by this component, e.g. `["token.ent_id"]`. Used for [pipe analysis](/usage/processing-pipelines#analysis). ~~Iterable[str]~~ |
-| `requires` | `Doc` or `Token` attributes required by this component, e.g. `["token.ent_id"]`. Used for [pipe analysis](/usage/processing-pipelines#analysis). ~~Iterable[str]~~ |
-| `retokenizes` | Whether the component changes tokenization. Used for [pipe analysis](/usage/processing-pipelines#analysis). ~~bool~~ |
+| `requires` | `Doc` or `Token` attributes required by this component, e.g. `["token.ent_id"]`. Used for [pipe analysis](/usage/processing-pipelines#analysis). ~~Iterable[str]~~ |
+| `retokenizes` | Whether the component changes tokenization. Used for [pipe analysis](/usage/processing-pipelines#analysis). ~~bool~~ |
| `default_score_weights` | The scores to report during training, and their default weight towards the final score used to select the best model. Weights should sum to `1.0` per component and will be combined and normalized for the whole pipeline. If a weight is set to `None`, the score will not be logged or weighted. ~~Dict[str, Optional[float]]~~ |
| `scores` | All scores set by the components if it's trainable, e.g. `["ents_f", "ents_r", "ents_p"]`. Based on the `default_score_weights` and used for [pipe analysis](/usage/processing-pipelines#analysis). ~~Iterable[str]~~ |
diff --git a/website/docs/api/legacy.md b/website/docs/api/legacy.mdx
similarity index 84%
rename from website/docs/api/legacy.md
rename to website/docs/api/legacy.mdx
index e24c37d77..ea6d3a899 100644
--- a/website/docs/api/legacy.md
+++ b/website/docs/api/legacy.mdx
@@ -12,11 +12,11 @@ functions that may still be used in projects.
You can find the detailed documentation of each such legacy function on this
page.
-## Architectures {#architectures}
+## Architectures {id="architectures"}
These functions are available from `@spacy.registry.architectures`.
-### spacy.Tok2Vec.v1 {#Tok2Vec_v1}
+### spacy.Tok2Vec.v1 {id="Tok2Vec_v1"}
The `spacy.Tok2Vec.v1` architecture was expecting an `encode` model of type
`Model[Floats2D, Floats2D]` such as `spacy.MaxoutWindowEncoder.v1` or
@@ -48,7 +48,7 @@ blog post for background.
| `encode` | Encode context into the embeddings, using an architecture such as a CNN, BiLSTM or transformer. For example, [MaxoutWindowEncoder.v1](/api/legacy#MaxoutWindowEncoder_v1). ~~Model[Floats2d, Floats2d]~~ |
| **CREATES** | The model using the architecture. ~~Model[List[Doc], List[Floats2d]]~~ |
-### spacy.MaxoutWindowEncoder.v1 {#MaxoutWindowEncoder_v1}
+### spacy.MaxoutWindowEncoder.v1 {id="MaxoutWindowEncoder_v1"}
The `spacy.MaxoutWindowEncoder.v1` architecture was producing a model of type
`Model[Floats2D, Floats2D]`. Since `spacy.MaxoutWindowEncoder.v2`, this has been
@@ -76,7 +76,7 @@ and residual connections.
| `depth` | The number of convolutional layers. Recommended value is `4`. ~~int~~ |
| **CREATES** | The model using the architecture. ~~Model[Floats2d, Floats2d]~~ |
-### spacy.MishWindowEncoder.v1 {#MishWindowEncoder_v1}
+### spacy.MishWindowEncoder.v1 {id="MishWindowEncoder_v1"}
The `spacy.MishWindowEncoder.v1` architecture was producing a model of type
`Model[Floats2D, Floats2D]`. Since `spacy.MishWindowEncoder.v2`, this has been
@@ -103,13 +103,24 @@ and residual connections.
| `depth` | The number of convolutional layers. Recommended value is `4`. ~~int~~ |
| **CREATES** | The model using the architecture. ~~Model[Floats2d, Floats2d]~~ |
-### spacy.TransitionBasedParser.v1 {#TransitionBasedParser_v1}
+### spacy.HashEmbedCNN.v1 {id="HashEmbedCNN_v1"}
-Identical to
-[`spacy.TransitionBasedParser.v2`](/api/architectures#TransitionBasedParser)
-except the `use_upper` was set to `True` by default.
+Identical to [`spacy.HashEmbedCNN.v2`](/api/architectures#HashEmbedCNN) except
+using [`spacy.StaticVectors.v1`](#StaticVectors_v1) if vectors are included.
-### spacy.TextCatEnsemble.v1 {#TextCatEnsemble_v1}
+### spacy.MultiHashEmbed.v1 {id="MultiHashEmbed_v1"}
+
+Identical to [`spacy.MultiHashEmbed.v2`](/api/architectures#MultiHashEmbed)
+except with [`spacy.StaticVectors.v1`](#StaticVectors_v1) if vectors are
+included.
+
+### spacy.CharacterEmbed.v1 {id="CharacterEmbed_v1"}
+
+Identical to [`spacy.CharacterEmbed.v2`](/api/architectures#CharacterEmbed)
+except using [`spacy.StaticVectors.v1`](#StaticVectors_v1) if vectors are
+included.
+
+### spacy.TextCatEnsemble.v1 {id="TextCatEnsemble_v1"}
The `spacy.TextCatEnsemble.v1` architecture built an internal `tok2vec` and
`linear_model`. Since `spacy.TextCatEnsemble.v2`, this has been refactored so
@@ -147,42 +158,7 @@ network has an internal CNN Tok2Vec layer and uses attention.
| `nO` | Output dimension, determined by the number of different labels. If not set, the [`TextCategorizer`](/api/textcategorizer) component will set it when `initialize` is called. ~~Optional[int]~~ |
| **CREATES** | The model using the architecture. ~~Model[List[Doc], Floats2d]~~ |
-### spacy.HashEmbedCNN.v1 {#HashEmbedCNN_v1}
-
-Identical to [`spacy.HashEmbedCNN.v2`](/api/architectures#HashEmbedCNN) except
-using [`spacy.StaticVectors.v1`](#StaticVectors_v1) if vectors are included.
-
-### spacy.MultiHashEmbed.v1 {#MultiHashEmbed_v1}
-
-Identical to [`spacy.MultiHashEmbed.v2`](/api/architectures#MultiHashEmbed)
-except with [`spacy.StaticVectors.v1`](#StaticVectors_v1) if vectors are
-included.
-
-### spacy.CharacterEmbed.v1 {#CharacterEmbed_v1}
-
-Identical to [`spacy.CharacterEmbed.v2`](/api/architectures#CharacterEmbed)
-except using [`spacy.StaticVectors.v1`](#StaticVectors_v1) if vectors are
-included.
-
-## Layers {#layers}
-
-These functions are available from `@spacy.registry.layers`.
-
-### spacy.StaticVectors.v1 {#StaticVectors_v1}
-
-Identical to [`spacy.StaticVectors.v2`](/api/architectures#StaticVectors) except
-for the handling of tokens without vectors.
-
-
-
-`spacy.StaticVectors.v1` maps tokens without vectors to the final row in the
-vectors table, which causes the model predictions to change if new vectors are
-added to an existing vectors table. See more details in
-[issue #7662](https://github.com/explosion/spaCy/issues/7662#issuecomment-813925655).
-
-
-
-### spacy.TextCatCNN.v1 {#TextCatCNN_v1}
+### spacy.TextCatCNN.v1 {id="TextCatCNN_v1"}
Since `spacy.TextCatCNN.v2`, this architecture has become resizable, which means
that you can add labels to a previously trained textcat. `TextCatCNN` v1 did not
@@ -218,7 +194,7 @@ architecture is usually less accurate than the ensemble, but runs faster.
| `nO` | Output dimension, determined by the number of different labels. If not set, the [`TextCategorizer`](/api/textcategorizer) component will set it when `initialize` is called. ~~Optional[int]~~ |
| **CREATES** | The model using the architecture. ~~Model[List[Doc], Floats2d]~~ |
-### spacy.TextCatBOW.v1 {#TextCatBOW_v1}
+### spacy.TextCatBOW.v1 {id="TextCatBOW_v1"}
Since `spacy.TextCatBOW.v2`, this architecture has become resizable, which means
that you can add labels to a previously trained textcat. `TextCatBOW` v1 did not
@@ -246,8 +222,88 @@ the others, but may not be as accurate, especially if texts are short.
| `nO` | Output dimension, determined by the number of different labels. If not set, the [`TextCategorizer`](/api/textcategorizer) component will set it when `initialize` is called. ~~Optional[int]~~ |
| **CREATES** | The model using the architecture. ~~Model[List[Doc], Floats2d]~~ |
-## Loggers {#loggers}
+### spacy.TransitionBasedParser.v1 {id="TransitionBasedParser_v1"}
-Logging utilities for spaCy are implemented in the [`spacy-loggers`](https://github.com/explosion/spacy-loggers) repo, and the functions are typically available from `@spacy.registry.loggers`.
+Identical to
+[`spacy.TransitionBasedParser.v2`](/api/architectures#TransitionBasedParser)
+except the `use_upper` was set to `True` by default.
-More documentation can be found in that repo's [readme](https://github.com/explosion/spacy-loggers/blob/main/README.md) file.
+## Layers {id="layers"}
+
+These functions are available from `@spacy.registry.layers`.
+
+### spacy.StaticVectors.v1 {id="StaticVectors_v1"}
+
+Identical to [`spacy.StaticVectors.v2`](/api/architectures#StaticVectors) except
+for the handling of tokens without vectors.
+
+
+
+`spacy.StaticVectors.v1` maps tokens without vectors to the final row in the
+vectors table, which causes the model predictions to change if new vectors are
+added to an existing vectors table. See more details in
+[issue #7662](https://github.com/explosion/spaCy/issues/7662#issuecomment-813925655).
+
+
+
+## Loggers {id="loggers"}
+
+These functions are available from `@spacy.registry.loggers`.
+
+### spacy.ConsoleLogger.v1 {id="ConsoleLogger_v1"}
+
+> #### Example config
+>
+> ```ini
+> [training.logger]
+> @loggers = "spacy.ConsoleLogger.v1"
+> progress_bar = true
+> ```
+
+Writes the results of a training step to the console in a tabular format.
+
+
+
+```bash
+$ python -m spacy train config.cfg
+```
+
+```
+ℹ Using CPU
+ℹ Loading config and nlp from: config.cfg
+ℹ Pipeline: ['tok2vec', 'tagger']
+ℹ Start training
+ℹ Training. Initial learn rate: 0.0
+
+E # LOSS TOK2VEC LOSS TAGGER TAG_ACC SCORE
+--- ------ ------------ ----------- ------- ------
+ 0 0 0.00 86.20 0.22 0.00
+ 0 200 3.08 18968.78 34.00 0.34
+ 0 400 31.81 22539.06 33.64 0.34
+ 0 600 92.13 22794.91 43.80 0.44
+ 0 800 183.62 21541.39 56.05 0.56
+ 0 1000 352.49 25461.82 65.15 0.65
+ 0 1200 422.87 23708.82 71.84 0.72
+ 0 1400 601.92 24994.79 76.57 0.77
+ 0 1600 662.57 22268.02 80.20 0.80
+ 0 1800 1101.50 28413.77 82.56 0.83
+ 0 2000 1253.43 28736.36 85.00 0.85
+ 0 2200 1411.02 28237.53 87.42 0.87
+ 0 2400 1605.35 28439.95 88.70 0.89
+```
+
+Note that the cumulative loss keeps increasing within one epoch, but should
+start decreasing across epochs.
+
+
+
+| Name | Description |
+| -------------- | --------------------------------------------------------- |
+| `progress_bar` | Whether the logger should print the progress bar ~~bool~~ |
+
+Logging utilities for spaCy are implemented in the
+[`spacy-loggers`](https://github.com/explosion/spacy-loggers) repo, and the
+functions are typically available from `@spacy.registry.loggers`.
+
+More documentation can be found in that repo's
+[readme](https://github.com/explosion/spacy-loggers/blob/main/README.md) file.
diff --git a/website/docs/api/lemmatizer.md b/website/docs/api/lemmatizer.mdx
similarity index 92%
rename from website/docs/api/lemmatizer.md
rename to website/docs/api/lemmatizer.mdx
index 2fa040917..f6657dbf4 100644
--- a/website/docs/api/lemmatizer.md
+++ b/website/docs/api/lemmatizer.mdx
@@ -2,21 +2,22 @@
title: Lemmatizer
tag: class
source: spacy/pipeline/lemmatizer.py
-new: 3
+version: 3
teaser: 'Pipeline component for lemmatization'
api_string_name: lemmatizer
api_trainable: false
---
Component for assigning base forms to tokens using rules based on part-of-speech
-tags, or lookup tables. Functionality to train the component is coming soon.
-Different [`Language`](/api/language) subclasses can implement their own
-lemmatizer components via
+tags, or lookup tables. Different [`Language`](/api/language) subclasses can
+implement their own lemmatizer components via
[language-specific factories](/usage/processing-pipelines#factories-language).
The default data used is provided by the
[`spacy-lookups-data`](https://github.com/explosion/spacy-lookups-data)
extension package.
+For a trainable lemmatizer, see [`EditTreeLemmatizer`](/api/edittreelemmatizer).
+
As of v3.0, the `Lemmatizer` is a **standalone pipeline component** that can be
@@ -31,7 +32,7 @@ available in the pipeline and runs _before_ the lemmatizer.
-## Assigned Attributes {#assigned-attributes}
+## Assigned Attributes {id="assigned-attributes"}
Lemmas generated by rules or predicted will be saved to `Token.lemma`.
@@ -69,7 +70,7 @@ lemmatizer is available. The lemmatizer modes `rule` and `pos_lookup` require
[`token.pos`](/api/token) from a previous pipeline component (see example
pipeline configurations in the
[pretrained pipeline design details](/models#design-cnn)) or rely on third-party
-libraries (`pymorphy2`).
+libraries (`pymorphy3`).
| Language | Default Mode |
| -------- | ------------ |
@@ -85,15 +86,15 @@ libraries (`pymorphy2`).
| `nb` | `rule` |
| `nl` | `rule` |
| `pl` | `pos_lookup` |
-| `ru` | `pymorphy2` |
+| `ru` | `pymorphy3` |
| `sv` | `rule` |
-| `uk` | `pymorphy2` |
+| `uk` | `pymorphy3` |
```python
%%GITHUB_SPACY/spacy/pipeline/lemmatizer.py
```
-## Lemmatizer.\_\_init\_\_ {#init tag="method"}
+## Lemmatizer.\_\_init\_\_ {id="init",tag="method"}
> #### Example
>
@@ -117,9 +118,9 @@ shortcut for this and instantiate the component using its string name and
| `name` | String name of the component instance. Used to add entries to the `losses` during training. ~~str~~ |
| _keyword-only_ | |
| mode | The lemmatizer mode, e.g. `"lookup"` or `"rule"`. Defaults to `"lookup"`. ~~str~~ |
-| overwrite | Whether to overwrite existing lemmas. ~~bool~ |
+| overwrite | Whether to overwrite existing lemmas. ~~bool~~ |
-## Lemmatizer.\_\_call\_\_ {#call tag="method"}
+## Lemmatizer.\_\_call\_\_ {id="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
@@ -139,7 +140,7 @@ and all pipeline components are applied to the `Doc` in order.
| `doc` | The document to process. ~~Doc~~ |
| **RETURNS** | The processed document. ~~Doc~~ |
-## Lemmatizer.pipe {#pipe tag="method"}
+## Lemmatizer.pipe {id="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
@@ -160,7 +161,7 @@ applied to the `Doc` in order.
| `batch_size` | The number of documents to buffer. Defaults to `128`. ~~int~~ |
| **YIELDS** | The processed documents in order. ~~Doc~~ |
-## Lemmatizer.initialize {#initialize tag="method"}
+## Lemmatizer.initialize {id="initialize",tag="method"}
Initialize the lemmatizer and load any data resources. This method is typically
called by [`Language.initialize`](/api/language#initialize) and lets you
@@ -191,7 +192,7 @@ training. At runtime, all data is loaded from disk.
| `nlp` | The current `nlp` object. Defaults to `None`. ~~Optional[Language]~~ |
| `lookups` | The lookups object containing the tables such as `"lemma_rules"`, `"lemma_index"`, `"lemma_exc"` and `"lemma_lookup"`. If `None`, default tables are loaded from [`spacy-lookups-data`](https://github.com/explosion/spacy-lookups-data). Defaults to `None`. ~~Optional[Lookups]~~ |
-## Lemmatizer.lookup_lemmatize {#lookup_lemmatize tag="method"}
+## Lemmatizer.lookup_lemmatize {id="lookup_lemmatize",tag="method"}
Lemmatize a token using a lookup-based approach. If no lemma is found, the
original string is returned.
@@ -201,7 +202,7 @@ original string is returned.
| `token` | The token to lemmatize. ~~Token~~ |
| **RETURNS** | A list containing one or more lemmas. ~~List[str]~~ |
-## Lemmatizer.rule_lemmatize {#rule_lemmatize tag="method"}
+## Lemmatizer.rule_lemmatize {id="rule_lemmatize",tag="method"}
Lemmatize a token using a rule-based approach. Typically relies on POS tags.
@@ -210,7 +211,7 @@ Lemmatize a token using a rule-based approach. Typically relies on POS tags.
| `token` | The token to lemmatize. ~~Token~~ |
| **RETURNS** | A list containing one or more lemmas. ~~List[str]~~ |
-## Lemmatizer.is_base_form {#is_base_form tag="method"}
+## Lemmatizer.is_base_form {id="is_base_form",tag="method"}
Check whether we're dealing with an uninflected paradigm, so we can avoid
lemmatization entirely.
@@ -220,7 +221,7 @@ lemmatization entirely.
| `token` | The token to analyze. ~~Token~~ |
| **RETURNS** | Whether the token's attributes (e.g., part-of-speech tag, morphological features) describe a base form. ~~bool~~ |
-## Lemmatizer.get_lookups_config {#get_lookups_config tag="classmethod"}
+## Lemmatizer.get_lookups_config {id="get_lookups_config",tag="classmethod"}
Returns the lookups configuration settings for a given mode for use in
[`Lemmatizer.load_lookups`](/api/lemmatizer#load_lookups).
@@ -230,7 +231,7 @@ Returns the lookups configuration settings for a given mode for use in
| `mode` | The lemmatizer mode. ~~str~~ |
| **RETURNS** | The required table names and the optional table names. ~~Tuple[List[str], List[str]]~~ |
-## Lemmatizer.to_disk {#to_disk tag="method"}
+## Lemmatizer.to_disk {id="to_disk",tag="method"}
Serialize the pipe to disk.
@@ -247,7 +248,7 @@ Serialize the pipe to disk.
| _keyword-only_ | |
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
-## Lemmatizer.from_disk {#from_disk tag="method"}
+## Lemmatizer.from_disk {id="from_disk",tag="method"}
Load the pipe from disk. Modifies the object in place and returns it.
@@ -265,7 +266,7 @@ Load the pipe from disk. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The modified `Lemmatizer` object. ~~Lemmatizer~~ |
-## Lemmatizer.to_bytes {#to_bytes tag="method"}
+## Lemmatizer.to_bytes {id="to_bytes",tag="method"}
> #### Example
>
@@ -282,7 +283,7 @@ Serialize the pipe to a bytestring.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The serialized form of the `Lemmatizer` object. ~~bytes~~ |
-## Lemmatizer.from_bytes {#from_bytes tag="method"}
+## Lemmatizer.from_bytes {id="from_bytes",tag="method"}
Load the pipe from a bytestring. Modifies the object in place and returns it.
@@ -301,7 +302,7 @@ Load the pipe from a bytestring. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The `Lemmatizer` object. ~~Lemmatizer~~ |
-## Attributes {#attributes}
+## Attributes {id="attributes"}
| Name | Description |
| --------- | ------------------------------------------- |
@@ -309,7 +310,7 @@ Load the pipe from a bytestring. Modifies the object in place and returns it.
| `lookups` | The lookups object. ~~Lookups~~ |
| `mode` | The lemmatizer mode. ~~str~~ |
-## Serialization fields {#serialization-fields}
+## Serialization fields {id="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
diff --git a/website/docs/api/lexeme.md b/website/docs/api/lexeme.md
deleted file mode 100644
index c5d4b7544..000000000
--- a/website/docs/api/lexeme.md
+++ /dev/null
@@ -1,164 +0,0 @@
----
-title: Lexeme
-teaser: An entry in the vocabulary
-tag: class
-source: spacy/lexeme.pyx
----
-
-A `Lexeme` has no string context – it's a word type, as opposed to a word token.
-It therefore has no part-of-speech tag, dependency parse, or lemma (if
-lemmatization depends on the part-of-speech tag).
-
-## Lexeme.\_\_init\_\_ {#init tag="method"}
-
-Create a `Lexeme` object.
-
-| Name | Description |
-| ------- | ---------------------------------- |
-| `vocab` | The parent vocabulary. ~~Vocab~~ |
-| `orth` | The orth id of the lexeme. ~~int~~ |
-
-## Lexeme.set_flag {#set_flag tag="method"}
-
-Change the value of a boolean flag.
-
-> #### Example
->
-> ```python
-> COOL_FLAG = nlp.vocab.add_flag(lambda text: False)
-> nlp.vocab["spaCy"].set_flag(COOL_FLAG, True)
-> ```
-
-| Name | Description |
-| --------- | -------------------------------------------- |
-| `flag_id` | The attribute ID of the flag to set. ~~int~~ |
-| `value` | The new value of the flag. ~~bool~~ |
-
-## Lexeme.check_flag {#check_flag tag="method"}
-
-Check the value of a boolean flag.
-
-> #### Example
->
-> ```python
-> is_my_library = lambda text: text in ["spaCy", "Thinc"]
-> MY_LIBRARY = nlp.vocab.add_flag(is_my_library)
-> assert nlp.vocab["spaCy"].check_flag(MY_LIBRARY) == True
-> ```
-
-| Name | Description |
-| ----------- | ---------------------------------------------- |
-| `flag_id` | The attribute ID of the flag to query. ~~int~~ |
-| **RETURNS** | The value of the flag. ~~bool~~ |
-
-## Lexeme.similarity {#similarity tag="method" model="vectors"}
-
-Compute a semantic similarity estimate. Defaults to cosine over vectors.
-
-> #### Example
->
-> ```python
-> apple = nlp.vocab["apple"]
-> orange = nlp.vocab["orange"]
-> apple_orange = apple.similarity(orange)
-> orange_apple = orange.similarity(apple)
-> assert apple_orange == orange_apple
-> ```
-
-| Name | Description |
-| ----------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| other | The object to compare with. By default, accepts `Doc`, `Span`, `Token` and `Lexeme` objects. ~~Union[Doc, Span, Token, Lexeme]~~ |
-| **RETURNS** | A scalar similarity score. Higher is more similar. ~~float~~ |
-
-## Lexeme.has_vector {#has_vector tag="property" model="vectors"}
-
-A boolean value indicating whether a word vector is associated with the lexeme.
-
-> #### Example
->
-> ```python
-> apple = nlp.vocab["apple"]
-> assert apple.has_vector
-> ```
-
-| Name | Description |
-| ----------- | ------------------------------------------------------- |
-| **RETURNS** | Whether the lexeme has a vector data attached. ~~bool~~ |
-
-## Lexeme.vector {#vector tag="property" model="vectors"}
-
-A real-valued meaning representation.
-
-> #### Example
->
-> ```python
-> apple = nlp.vocab["apple"]
-> assert apple.vector.dtype == "float32"
-> assert apple.vector.shape == (300,)
-> ```
-
-| Name | Description |
-| ----------- | ------------------------------------------------------------------------------------------------ |
-| **RETURNS** | A 1-dimensional array representing the lexeme's vector. ~~numpy.ndarray[ndim=1, dtype=float32]~~ |
-
-## Lexeme.vector_norm {#vector_norm tag="property" model="vectors"}
-
-The L2 norm of the lexeme's vector representation.
-
-> #### Example
->
-> ```python
-> apple = nlp.vocab["apple"]
-> pasta = nlp.vocab["pasta"]
-> apple.vector_norm # 7.1346845626831055
-> pasta.vector_norm # 7.759851932525635
-> assert apple.vector_norm != pasta.vector_norm
-> ```
-
-| Name | Description |
-| ----------- | --------------------------------------------------- |
-| **RETURNS** | The L2 norm of the vector representation. ~~float~~ |
-
-## Attributes {#attributes}
-
-| Name | Description |
-| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `vocab` | The lexeme's vocabulary. ~~Vocab~~ |
-| `text` | Verbatim text content. ~~str~~ |
-| `orth` | ID of the verbatim text content. ~~int~~ |
-| `orth_` | Verbatim text content (identical to `Lexeme.text`). Exists mostly for consistency with the other attributes. ~~str~~ |
-| `rank` | Sequential ID of the lexeme's lexical type, used to index into tables, e.g. for word vectors. ~~int~~ |
-| `flags` | Container of the lexeme's binary flags. ~~int~~ |
-| `norm` | The lexeme's norm, i.e. a normalized form of the lexeme text. ~~int~~ |
-| `norm_` | The lexeme's norm, i.e. a normalized form of the lexeme text. ~~str~~ |
-| `lower` | Lowercase form of the word. ~~int~~ |
-| `lower_` | Lowercase form of the word. ~~str~~ |
-| `shape` | Transform of the word's string, to show orthographic features. Alphabetic characters are replaced by `x` or `X`, and numeric characters are replaced by `d`, and sequences of the same character are truncated after length 4. For example,`"Xxxx"`or`"dd"`. ~~int~~ |
-| `shape_` | Transform of the word's string, to show orthographic features. Alphabetic characters are replaced by `x` or `X`, and numeric characters are replaced by `d`, and sequences of the same character are truncated after length 4. For example,`"Xxxx"`or`"dd"`. ~~str~~ |
-| `prefix` | Length-N substring from the start of the word. Defaults to `N=1`. ~~int~~ |
-| `prefix_` | Length-N substring from the start of the word. Defaults to `N=1`. ~~str~~ |
-| `suffix` | Length-N substring from the end of the word. Defaults to `N=3`. ~~int~~ |
-| `suffix_` | Length-N substring from the start of the word. Defaults to `N=3`. ~~str~~ |
-| `is_alpha` | Does the lexeme consist of alphabetic characters? Equivalent to `lexeme.text.isalpha()`. ~~bool~~ |
-| `is_ascii` | Does the lexeme consist of ASCII characters? Equivalent to `[any(ord(c) >= 128 for c in lexeme.text)]`. ~~bool~~ |
-| `is_digit` | Does the lexeme consist of digits? Equivalent to `lexeme.text.isdigit()`. ~~bool~~ |
-| `is_lower` | Is the lexeme in lowercase? Equivalent to `lexeme.text.islower()`. ~~bool~~ |
-| `is_upper` | Is the lexeme in uppercase? Equivalent to `lexeme.text.isupper()`. ~~bool~~ |
-| `is_title` | Is the lexeme in titlecase? Equivalent to `lexeme.text.istitle()`. ~~bool~~ |
-| `is_punct` | Is the lexeme punctuation? ~~bool~~ |
-| `is_left_punct` | Is the lexeme a left punctuation mark, e.g. `(`? ~~bool~~ |
-| `is_right_punct` | Is the lexeme a right punctuation mark, e.g. `)`? ~~bool~~ |
-| `is_space` | Does the lexeme consist of whitespace characters? Equivalent to `lexeme.text.isspace()`. ~~bool~~ |
-| `is_bracket` | Is the lexeme a bracket? ~~bool~~ |
-| `is_quote` | Is the lexeme a quotation mark? ~~bool~~ |
-| `is_currency` 2.0.8 | Is the lexeme a currency symbol? ~~bool~~ |
-| `like_url` | Does the lexeme resemble a URL? ~~bool~~ |
-| `like_num` | Does the lexeme represent a number? e.g. "10.9", "10", "ten", etc. ~~bool~~ |
-| `like_email` | Does the lexeme resemble an email address? ~~bool~~ |
-| `is_oov` | Is the lexeme out-of-vocabulary (i.e. does it not have a word vector)? ~~bool~~ |
-| `is_stop` | Is the lexeme part of a "stop list"? ~~bool~~ |
-| `lang` | Language of the parent vocabulary. ~~int~~ |
-| `lang_` | Language of the parent vocabulary. ~~str~~ |
-| `prob` | Smoothed log probability estimate of the lexeme's word type (context-independent entry in the vocabulary). ~~float~~ |
-| `cluster` | Brown cluster ID. ~~int~~ |
-| `sentiment` | A scalar value indicating the positivity or negativity of the lexeme. ~~float~~ |
diff --git a/website/docs/api/lexeme.mdx b/website/docs/api/lexeme.mdx
new file mode 100644
index 000000000..539f502f0
--- /dev/null
+++ b/website/docs/api/lexeme.mdx
@@ -0,0 +1,164 @@
+---
+title: Lexeme
+teaser: An entry in the vocabulary
+tag: class
+source: spacy/lexeme.pyx
+---
+
+A `Lexeme` has no string context – it's a word type, as opposed to a word token.
+It therefore has no part-of-speech tag, dependency parse, or lemma (if
+lemmatization depends on the part-of-speech tag).
+
+## Lexeme.\_\_init\_\_ {id="init",tag="method"}
+
+Create a `Lexeme` object.
+
+| Name | Description |
+| ------- | ---------------------------------- |
+| `vocab` | The parent vocabulary. ~~Vocab~~ |
+| `orth` | The orth id of the lexeme. ~~int~~ |
+
+## Lexeme.set_flag {id="set_flag",tag="method"}
+
+Change the value of a boolean flag.
+
+> #### Example
+>
+> ```python
+> COOL_FLAG = nlp.vocab.add_flag(lambda text: False)
+> nlp.vocab["spaCy"].set_flag(COOL_FLAG, True)
+> ```
+
+| Name | Description |
+| --------- | -------------------------------------------- |
+| `flag_id` | The attribute ID of the flag to set. ~~int~~ |
+| `value` | The new value of the flag. ~~bool~~ |
+
+## Lexeme.check_flag {id="check_flag",tag="method"}
+
+Check the value of a boolean flag.
+
+> #### Example
+>
+> ```python
+> is_my_library = lambda text: text in ["spaCy", "Thinc"]
+> MY_LIBRARY = nlp.vocab.add_flag(is_my_library)
+> assert nlp.vocab["spaCy"].check_flag(MY_LIBRARY) == True
+> ```
+
+| Name | Description |
+| ----------- | ---------------------------------------------- |
+| `flag_id` | The attribute ID of the flag to query. ~~int~~ |
+| **RETURNS** | The value of the flag. ~~bool~~ |
+
+## Lexeme.similarity {id="similarity",tag="method",model="vectors"}
+
+Compute a semantic similarity estimate. Defaults to cosine over vectors.
+
+> #### Example
+>
+> ```python
+> apple = nlp.vocab["apple"]
+> orange = nlp.vocab["orange"]
+> apple_orange = apple.similarity(orange)
+> orange_apple = orange.similarity(apple)
+> assert apple_orange == orange_apple
+> ```
+
+| Name | Description |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| other | The object to compare with. By default, accepts `Doc`, `Span`, `Token` and `Lexeme` objects. ~~Union[Doc, Span, Token, Lexeme]~~ |
+| **RETURNS** | A scalar similarity score. Higher is more similar. ~~float~~ |
+
+## Lexeme.has_vector {id="has_vector",tag="property",model="vectors"}
+
+A boolean value indicating whether a word vector is associated with the lexeme.
+
+> #### Example
+>
+> ```python
+> apple = nlp.vocab["apple"]
+> assert apple.has_vector
+> ```
+
+| Name | Description |
+| ----------- | ------------------------------------------------------- |
+| **RETURNS** | Whether the lexeme has a vector data attached. ~~bool~~ |
+
+## Lexeme.vector {id="vector",tag="property",model="vectors"}
+
+A real-valued meaning representation.
+
+> #### Example
+>
+> ```python
+> apple = nlp.vocab["apple"]
+> assert apple.vector.dtype == "float32"
+> assert apple.vector.shape == (300,)
+> ```
+
+| Name | Description |
+| ----------- | ------------------------------------------------------------------------------------------------ |
+| **RETURNS** | A 1-dimensional array representing the lexeme's vector. ~~numpy.ndarray[ndim=1, dtype=float32]~~ |
+
+## Lexeme.vector_norm {id="vector_norm",tag="property",model="vectors"}
+
+The L2 norm of the lexeme's vector representation.
+
+> #### Example
+>
+> ```python
+> apple = nlp.vocab["apple"]
+> pasta = nlp.vocab["pasta"]
+> apple.vector_norm # 7.1346845626831055
+> pasta.vector_norm # 7.759851932525635
+> assert apple.vector_norm != pasta.vector_norm
+> ```
+
+| Name | Description |
+| ----------- | --------------------------------------------------- |
+| **RETURNS** | The L2 norm of the vector representation. ~~float~~ |
+
+## Attributes {id="attributes"}
+
+| Name | Description |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `vocab` | The lexeme's vocabulary. ~~Vocab~~ |
+| `text` | Verbatim text content. ~~str~~ |
+| `orth` | ID of the verbatim text content. ~~int~~ |
+| `orth_` | Verbatim text content (identical to `Lexeme.text`). Exists mostly for consistency with the other attributes. ~~str~~ |
+| `rank` | Sequential ID of the lexeme's lexical type, used to index into tables, e.g. for word vectors. ~~int~~ |
+| `flags` | Container of the lexeme's binary flags. ~~int~~ |
+| `norm` | The lexeme's norm, i.e. a normalized form of the lexeme text. ~~int~~ |
+| `norm_` | The lexeme's norm, i.e. a normalized form of the lexeme text. ~~str~~ |
+| `lower` | Lowercase form of the word. ~~int~~ |
+| `lower_` | Lowercase form of the word. ~~str~~ |
+| `shape` | Transform of the word's string, to show orthographic features. Alphabetic characters are replaced by `x` or `X`, and numeric characters are replaced by `d`, and sequences of the same character are truncated after length 4. For example,`"Xxxx"`or`"dd"`. ~~int~~ |
+| `shape_` | Transform of the word's string, to show orthographic features. Alphabetic characters are replaced by `x` or `X`, and numeric characters are replaced by `d`, and sequences of the same character are truncated after length 4. For example,`"Xxxx"`or`"dd"`. ~~str~~ |
+| `prefix` | Length-N substring from the start of the word. Defaults to `N=1`. ~~int~~ |
+| `prefix_` | Length-N substring from the start of the word. Defaults to `N=1`. ~~str~~ |
+| `suffix` | Length-N substring from the end of the word. Defaults to `N=3`. ~~int~~ |
+| `suffix_` | Length-N substring from the end of the word. Defaults to `N=3`. ~~str~~ |
+| `is_alpha` | Does the lexeme consist of alphabetic characters? Equivalent to `lexeme.text.isalpha()`. ~~bool~~ |
+| `is_ascii` | Does the lexeme consist of ASCII characters? Equivalent to `[any(ord(c) >= 128 for c in lexeme.text)]`. ~~bool~~ |
+| `is_digit` | Does the lexeme consist of digits? Equivalent to `lexeme.text.isdigit()`. ~~bool~~ |
+| `is_lower` | Is the lexeme in lowercase? Equivalent to `lexeme.text.islower()`. ~~bool~~ |
+| `is_upper` | Is the lexeme in uppercase? Equivalent to `lexeme.text.isupper()`. ~~bool~~ |
+| `is_title` | Is the lexeme in titlecase? Equivalent to `lexeme.text.istitle()`. ~~bool~~ |
+| `is_punct` | Is the lexeme punctuation? ~~bool~~ |
+| `is_left_punct` | Is the lexeme a left punctuation mark, e.g. `(`? ~~bool~~ |
+| `is_right_punct` | Is the lexeme a right punctuation mark, e.g. `)`? ~~bool~~ |
+| `is_space` | Does the lexeme consist of whitespace characters? Equivalent to `lexeme.text.isspace()`. ~~bool~~ |
+| `is_bracket` | Is the lexeme a bracket? ~~bool~~ |
+| `is_quote` | Is the lexeme a quotation mark? ~~bool~~ |
+| `is_currency` | Is the lexeme a currency symbol? ~~bool~~ |
+| `like_url` | Does the lexeme resemble a URL? ~~bool~~ |
+| `like_num` | Does the lexeme represent a number? e.g. "10.9", "10", "ten", etc. ~~bool~~ |
+| `like_email` | Does the lexeme resemble an email address? ~~bool~~ |
+| `is_oov` | Is the lexeme out-of-vocabulary (i.e. does it not have a word vector)? ~~bool~~ |
+| `is_stop` | Is the lexeme part of a "stop list"? ~~bool~~ |
+| `lang` | Language of the parent vocabulary. ~~int~~ |
+| `lang_` | Language of the parent vocabulary. ~~str~~ |
+| `prob` | Smoothed log probability estimate of the lexeme's word type (context-independent entry in the vocabulary). ~~float~~ |
+| `cluster` | Brown cluster ID. ~~int~~ |
+| `sentiment` | A scalar value indicating the positivity or negativity of the lexeme. ~~float~~ |
diff --git a/website/docs/api/lookups.md b/website/docs/api/lookups.mdx
similarity index 89%
rename from website/docs/api/lookups.md
rename to website/docs/api/lookups.mdx
index 9565e478f..71a857c60 100644
--- a/website/docs/api/lookups.md
+++ b/website/docs/api/lookups.mdx
@@ -3,7 +3,7 @@ title: Lookups
teaser: A container for large lookup tables and dictionaries
tag: class
source: spacy/lookups.py
-new: 2.2
+version: 2.2
---
This class allows convenient access to large lookup tables and dictionaries,
@@ -13,7 +13,7 @@ can be accessed before the pipeline components are applied (e.g. in the
tokenizer and lemmatizer), as well as within the pipeline components via
`doc.vocab.lookups`.
-## Lookups.\_\_init\_\_ {#init tag="method"}
+## Lookups.\_\_init\_\_ {id="init",tag="method"}
Create a `Lookups` object.
@@ -24,7 +24,7 @@ Create a `Lookups` object.
> lookups = Lookups()
> ```
-## Lookups.\_\_len\_\_ {#len tag="method"}
+## Lookups.\_\_len\_\_ {id="len",tag="method"}
Get the current number of tables in the lookups.
@@ -39,7 +39,7 @@ Get the current number of tables in the lookups.
| ----------- | -------------------------------------------- |
| **RETURNS** | The number of tables in the lookups. ~~int~~ |
-## Lookups.\_\contains\_\_ {#contains tag="method"}
+## Lookups.\_\_contains\_\_ {id="contains",tag="method"}
Check if the lookups contain a table of a given name. Delegates to
[`Lookups.has_table`](/api/lookups#has_table).
@@ -57,7 +57,7 @@ Check if the lookups contain a table of a given name. Delegates to
| `name` | Name of the table. ~~str~~ |
| **RETURNS** | Whether a table of that name is in the lookups. ~~bool~~ |
-## Lookups.tables {#tables tag="property"}
+## Lookups.tables {id="tables",tag="property"}
Get the names of all tables in the lookups.
@@ -73,7 +73,7 @@ Get the names of all tables in the lookups.
| ----------- | ------------------------------------------------- |
| **RETURNS** | Names of the tables in the lookups. ~~List[str]~~ |
-## Lookups.add_table {#add_table tag="method"}
+## Lookups.add_table {id="add_table",tag="method"}
Add a new table with optional data to the lookups. Raises an error if the table
exists.
@@ -91,7 +91,7 @@ exists.
| `data` | Optional data to add to the table. ~~dict~~ |
| **RETURNS** | The newly added table. ~~Table~~ |
-## Lookups.get_table {#get_table tag="method"}
+## Lookups.get_table {id="get_table",tag="method"}
Get a table from the lookups. Raises an error if the table doesn't exist.
@@ -109,7 +109,7 @@ Get a table from the lookups. Raises an error if the table doesn't exist.
| `name` | Name of the table. ~~str~~ |
| **RETURNS** | The table. ~~Table~~ |
-## Lookups.remove_table {#remove_table tag="method"}
+## Lookups.remove_table {id="remove_table",tag="method"}
Remove a table from the lookups. Raises an error if the table doesn't exist.
@@ -127,7 +127,7 @@ Remove a table from the lookups. Raises an error if the table doesn't exist.
| `name` | Name of the table to remove. ~~str~~ |
| **RETURNS** | The removed table. ~~Table~~ |
-## Lookups.has_table {#has_table tag="method"}
+## Lookups.has_table {id="has_table",tag="method"}
Check if the lookups contain a table of a given name. Equivalent to
[`Lookups.__contains__`](/api/lookups#contains).
@@ -145,7 +145,7 @@ Check if the lookups contain a table of a given name. Equivalent to
| `name` | Name of the table. ~~str~~ |
| **RETURNS** | Whether a table of that name is in the lookups. ~~bool~~ |
-## Lookups.to_bytes {#to_bytes tag="method"}
+## Lookups.to_bytes {id="to_bytes",tag="method"}
Serialize the lookups to a bytestring.
@@ -159,7 +159,7 @@ Serialize the lookups to a bytestring.
| ----------- | --------------------------------- |
| **RETURNS** | The serialized lookups. ~~bytes~~ |
-## Lookups.from_bytes {#from_bytes tag="method"}
+## Lookups.from_bytes {id="from_bytes",tag="method"}
Load the lookups from a bytestring.
@@ -176,7 +176,7 @@ Load the lookups from a bytestring.
| `bytes_data` | The data to load from. ~~bytes~~ |
| **RETURNS** | The loaded lookups. ~~Lookups~~ |
-## Lookups.to_disk {#to_disk tag="method"}
+## Lookups.to_disk {id="to_disk",tag="method"}
Save the lookups to a directory as `lookups.bin`. Expects a path to a directory,
which will be created if it doesn't exist.
@@ -191,7 +191,7 @@ which will be created if it doesn't exist.
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `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]~~ |
-## Lookups.from_disk {#from_disk tag="method"}
+## Lookups.from_disk {id="from_disk",tag="method"}
Load lookups from a directory containing a `lookups.bin`. Will skip loading if
the file doesn't exist.
@@ -209,7 +209,7 @@ the file doesn't exist.
| `path` | A path to a directory. Paths may be either strings or `Path`-like objects. ~~Union[str, Path]~~ |
| **RETURNS** | The loaded lookups. ~~Lookups~~ |
-## Table {#table tag="class, ordererddict"}
+## Table {id="table",tag="class, ordererddict"}
A table in the lookups. Subclass of `OrderedDict` that implements a slightly
more consistent and unified API and includes a Bloom filter to speed up missed
@@ -218,7 +218,7 @@ lookups. Supports **all other methods and attributes** of `OrderedDict` /
accept both integers and strings (which will be hashed before being added to the
table).
-### Table.\_\_init\_\_ {#table.init tag="method"}
+### Table.\_\_init\_\_ {id="table.init",tag="method"}
Initialize a new table.
@@ -236,7 +236,7 @@ Initialize a new table.
| ------ | ------------------------------------------ |
| `name` | Optional table name for reference. ~~str~~ |
-### Table.from_dict {#table.from_dict tag="classmethod"}
+### Table.from_dict {id="table.from_dict",tag="classmethod"}
Initialize a new table from a dict.
@@ -254,7 +254,7 @@ Initialize a new table from a dict.
| `name` | Optional table name for reference. ~~str~~ |
| **RETURNS** | The newly constructed object. ~~Table~~ |
-### Table.set {#table.set tag="method"}
+### Table.set {id="table.set",tag="method"}
Set a new key / value pair. String keys will be hashed. Same as
`table[key] = value`.
@@ -273,7 +273,7 @@ Set a new key / value pair. String keys will be hashed. Same as
| `key` | The key. ~~Union[str, int]~~ |
| `value` | The value. |
-### Table.to_bytes {#table.to_bytes tag="method"}
+### Table.to_bytes {id="table.to_bytes",tag="method"}
Serialize the table to a bytestring.
@@ -287,7 +287,7 @@ Serialize the table to a bytestring.
| ----------- | ------------------------------- |
| **RETURNS** | The serialized table. ~~bytes~~ |
-### Table.from_bytes {#table.from_bytes tag="method"}
+### Table.from_bytes {id="table.from_bytes",tag="method"}
Load a table from a bytestring.
@@ -304,7 +304,7 @@ Load a table from a bytestring.
| `bytes_data` | The data to load. ~~bytes~~ |
| **RETURNS** | The loaded table. ~~Table~~ |
-### Attributes {#table-attributes}
+### Attributes {id="table-attributes"}
| Name | Description |
| -------------- | ------------------------------------------------------------- |
diff --git a/website/docs/api/matcher.md b/website/docs/api/matcher.mdx
similarity index 54%
rename from website/docs/api/matcher.md
rename to website/docs/api/matcher.mdx
index 3e7f9dc04..c66579da8 100644
--- a/website/docs/api/matcher.md
+++ b/website/docs/api/matcher.mdx
@@ -13,7 +13,7 @@ tokens in context. For in-depth examples and workflows for combining rules and
statistical models, see the [usage guide](/usage/rule-based-matching) on
rule-based matching.
-## Pattern format {#patterns}
+## Pattern format {id="patterns"}
> ```json
> ### Example
@@ -30,25 +30,26 @@ pattern keys correspond to a number of
[`Token` attributes](/api/token#attributes). The supported attributes for
rule-based matching are:
-| Attribute | Description |
-| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `ORTH` | The exact verbatim text of a token. ~~str~~ |
-| `TEXT` 2.1 | The exact verbatim text of a token. ~~str~~ |
-| `LOWER` | The lowercase form of the token text. ~~str~~ |
-| `LENGTH` | The length of the token text. ~~int~~ |
-| `IS_ALPHA`, `IS_ASCII`, `IS_DIGIT` | Token text consists of alphabetic characters, ASCII characters, digits. ~~bool~~ |
-| `IS_LOWER`, `IS_UPPER`, `IS_TITLE` | Token text is in lowercase, uppercase, titlecase. ~~bool~~ |
-| `IS_PUNCT`, `IS_SPACE`, `IS_STOP` | Token is punctuation, whitespace, stop word. ~~bool~~ |
-| `IS_SENT_START` | Token is start of sentence. ~~bool~~ |
-| `LIKE_NUM`, `LIKE_URL`, `LIKE_EMAIL` | Token text resembles a number, URL, email. ~~bool~~ |
-| `SPACY` | Token has a trailing space. ~~bool~~ |
-| `POS`, `TAG`, `MORPH`, `DEP`, `LEMMA`, `SHAPE` | The token's simple and extended part-of-speech tag, morphological analysis, dependency label, lemma, shape. ~~str~~ |
-| `ENT_TYPE` | The token's entity label. ~~str~~ |
-| `ENT_IOB` | The IOB part of the token's entity tag. ~~str~~ |
-| `ENT_ID` | The token's entity ID (`ent_id`). ~~str~~ |
-| `ENT_KB_ID` | The token's entity knowledge base ID (`ent_kb_id`). ~~str~~ |
-| `_` 2.1 | Properties in [custom extension attributes](/usage/processing-pipelines#custom-components-attributes). ~~Dict[str, Any]~~ |
-| `OP` | Operator or quantifier to determine how often to match a token pattern. ~~str~~ |
+| Attribute | Description |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `ORTH` | The exact verbatim text of a token. ~~str~~ |
+| `TEXT` | The exact verbatim text of a token. ~~str~~ |
+| `NORM` | The normalized form of the token text. ~~str~~ |
+| `LOWER` | The lowercase form of the token text. ~~str~~ |
+| `LENGTH` | The length of the token text. ~~int~~ |
+| `IS_ALPHA`, `IS_ASCII`, `IS_DIGIT` | Token text consists of alphabetic characters, ASCII characters, digits. ~~bool~~ |
+| `IS_LOWER`, `IS_UPPER`, `IS_TITLE` | Token text is in lowercase, uppercase, titlecase. ~~bool~~ |
+| `IS_PUNCT`, `IS_SPACE`, `IS_STOP` | Token is punctuation, whitespace, stop word. ~~bool~~ |
+| `IS_SENT_START` | Token is start of sentence. ~~bool~~ |
+| `LIKE_NUM`, `LIKE_URL`, `LIKE_EMAIL` | Token text resembles a number, URL, email. ~~bool~~ |
+| `SPACY` | Token has a trailing space. ~~bool~~ |
+| `POS`, `TAG`, `MORPH`, `DEP`, `LEMMA`, `SHAPE` | The token's simple and extended part-of-speech tag, morphological analysis, dependency label, lemma, shape. ~~str~~ |
+| `ENT_TYPE` | The token's entity label. ~~str~~ |
+| `ENT_IOB` | The IOB part of the token's entity tag. ~~str~~ |
+| `ENT_ID` | The token's entity ID (`ent_id`). ~~str~~ |
+| `ENT_KB_ID` | The token's entity knowledge base ID (`ent_kb_id`). ~~str~~ |
+| `_` | Properties in [custom extension attributes](/usage/processing-pipelines#custom-components-attributes). ~~Dict[str, Any]~~ |
+| `OP` | Operator or quantifier to determine how often to match a token pattern. ~~str~~ |
Operators and quantifiers define **how often** a token pattern should be
matched:
@@ -58,15 +59,20 @@ matched:
> [
> {"POS": "ADJ", "OP": "*"},
> {"POS": "NOUN", "OP": "+"}
+> {"POS": "PROPN", "OP": "{2}"}
> ]
> ```
-| OP | Description |
-| --- | ---------------------------------------------------------------- |
-| `!` | Negate the pattern, by requiring it to match exactly 0 times. |
-| `?` | Make the pattern optional, by allowing it to match 0 or 1 times. |
-| `+` | Require the pattern to match 1 or more times. |
-| `*` | Allow the pattern to match 0 or more times. |
+| OP | Description |
+| ------- | ---------------------------------------------------------------------- |
+| `!` | Negate the pattern, by requiring it to match exactly 0 times. |
+| `?` | Make the pattern optional, by allowing it to match 0 or 1 times. |
+| `+` | Require the pattern to match 1 or more times. |
+| `*` | Allow the pattern to match 0 or more times. |
+| `{n}` | Require the pattern to match exactly _n_ times. |
+| `{n,m}` | Require the pattern to match at least _n_ but not more than _m_ times. |
+| `{n,}` | Require the pattern to match at least _n_ times. |
+| `{,m}` | Require the pattern to match at most _m_ times. |
Token patterns can also map to a **dictionary of properties** instead of a
single value to indicate whether the expected value is a member of a list or how
@@ -80,16 +86,22 @@ it compares to another value.
> ]
> ```
-| Attribute | Description |
-| -------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `IN` | Attribute value is member of a list. ~~Any~~ |
-| `NOT_IN` | Attribute value is _not_ member of a list. ~~Any~~ |
-| `IS_SUBSET` | Attribute value (for `MORPH` or custom list attributes) is a subset of a list. ~~Any~~ |
-| `IS_SUPERSET` | Attribute value (for `MORPH` or custom list attributes) is a superset of a list. ~~Any~~ |
-| `INTERSECTS` | Attribute value (for `MORPH` or custom list attribute) has a non-empty intersection with a list. ~~Any~~ |
-| `==`, `>=`, `<=`, `>`, `<` | Attribute value is equal, greater or equal, smaller or equal, greater or smaller. ~~Union[int, float]~~ |
+| Attribute | Description |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `REGEX` | Attribute value matches the regular expression at any position in the string. ~~Any~~ |
+| `FUZZY` | Attribute value matches if the `fuzzy_compare` method matches for `(value, pattern, -1)`. The default method allows a Levenshtein edit distance of at least 2 and up to 30% of the pattern string length. ~~Any~~ |
+| `FUZZY1`, `FUZZY2`, ... `FUZZY9` | Attribute value matches if the `fuzzy_compare` method matches for `(value, pattern, N)`. The default method allows a Levenshtein edit distance of at most N (1-9). ~~Any~~ |
+| `IN` | Attribute value is member of a list. ~~Any~~ |
+| `NOT_IN` | Attribute value is _not_ member of a list. ~~Any~~ |
+| `IS_SUBSET` | Attribute value (for `MORPH` or custom list attributes) is a subset of a list. ~~Any~~ |
+| `IS_SUPERSET` | Attribute value (for `MORPH` or custom list attributes) is a superset of a list. ~~Any~~ |
+| `INTERSECTS` | Attribute value (for `MORPH` or custom list attribute) has a non-empty intersection with a list. ~~Any~~ |
+| `==`, `>=`, `<=`, `>`, `<` | Attribute value is equal, greater or equal, smaller or equal, greater or smaller. ~~Union[int, float]~~ |
-## Matcher.\_\_init\_\_ {#init tag="method"}
+As of spaCy v3.5, `REGEX` and `FUZZY` can be used in combination with `IN` and
+`NOT_IN`.
+
+## Matcher.\_\_init\_\_ {id="init",tag="method"}
Create the rule-based `Matcher`. If `validate=True` is set, all patterns added
to the matcher will be validated against a JSON schema and a `MatchPatternError`
@@ -103,15 +115,20 @@ string where an integer is expected) or unexpected property names.
> matcher = Matcher(nlp.vocab)
> ```
-| Name | Description |
-| --------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| `vocab` | The vocabulary object, which must be shared with the documents the matcher will operate on. ~~Vocab~~ |
-| `validate` 2.1 | Validate all patterns added to this matcher. ~~bool~~ |
+| Name | Description |
+| --------------- | ----------------------------------------------------------------------------------------------------- |
+| `vocab` | The vocabulary object, which must be shared with the documents the matcher will operate on. ~~Vocab~~ |
+| `validate` | Validate all patterns added to this matcher. ~~bool~~ |
+| `fuzzy_compare` | The comparison method used for the `FUZZY` operators. ~~Callable[[str, str, int], bool]~~ |
-## Matcher.\_\_call\_\_ {#call tag="method"}
+## Matcher.\_\_call\_\_ {id="call",tag="method"}
Find all token sequences matching the supplied patterns on the `Doc` or `Span`.
+Note that if a single label has multiple patterns associated with it, the
+returned matches don't provide a way to tell which pattern was responsible for
+the match.
+
> #### Example
>
> ```python
@@ -130,10 +147,10 @@ Find all token sequences matching the supplied patterns on the `Doc` or `Span`.
| _keyword-only_ | |
| `as_spans` 3 | Instead of tuples, return a list of [`Span`](/api/span) objects of the matches, with the `match_id` assigned as the span label. Defaults to `False`. ~~bool~~ |
| `allow_missing` 3 | Whether to skip checks for missing annotation for attributes included in patterns. Defaults to `False`. ~~bool~~ |
-| `with_alignments` 3.0.6 | Return match alignment information as part of the match tuple as `List[int]` with the same length as the matched span. Each entry denotes the corresponding index of the token pattern. If `as_spans` is set to `True`, this setting is ignored. Defaults to `False`. ~~bool~~ |
+| `with_alignments` 3.0.6 | Return match alignment information as part of the match tuple as `List[int]` with the same length as the matched span. Each entry denotes the corresponding index of the token in the pattern. If `as_spans` is set to `True`, this setting is ignored. Defaults to `False`. ~~bool~~ |
| **RETURNS** | A list of `(match_id, start, end)` tuples, describing the matches. A match tuple describes a span `doc[start:end`]. The `match_id` is the ID of the added match pattern. If `as_spans` is set to `True`, a list of `Span` objects is returned instead. ~~Union[List[Tuple[int, int, int]], List[Span]]~~ |
-## Matcher.\_\_len\_\_ {#len tag="method" new="2"}
+## Matcher.\_\_len\_\_ {id="len",tag="method",version="2"}
Get the number of rules added to the matcher. Note that this only returns the
number of rules (identical with the number of IDs), not the number of individual
@@ -152,7 +169,7 @@ patterns.
| ----------- | ---------------------------- |
| **RETURNS** | The number of rules. ~~int~~ |
-## Matcher.\_\_contains\_\_ {#contains tag="method" new="2"}
+## Matcher.\_\_contains\_\_ {id="contains",tag="method",version="2"}
Check whether the matcher contains rules for a match ID.
@@ -170,7 +187,7 @@ Check whether the matcher contains rules for a match ID.
| `key` | The match ID. ~~str~~ |
| **RETURNS** | Whether the matcher contains rules for this match ID. ~~bool~~ |
-## Matcher.add {#add tag="method" new="2"}
+## Matcher.add {id="add",tag="method",version="2"}
Add a rule to the matcher, consisting of an ID key, one or more patterns, and an
optional callback function to act on the matches. The callback function will
@@ -189,7 +206,7 @@ will be overwritten.
> [{"LOWER": "hello"}, {"LOWER": "world"}],
> [{"ORTH": "Google"}, {"ORTH": "Maps"}]
> ]
-> matcher.add("TEST_PATTERNS", patterns)
+> matcher.add("TEST_PATTERNS", patterns, on_match=on_match)
> doc = nlp("HELLO WORLD on Google Maps.")
> matches = matcher(doc)
> ```
@@ -216,7 +233,7 @@ patterns = [[{"TEXT": "Google"}, {"TEXT": "Now"}], [{"TEXT": "GoogleNow"}]]
| `on_match` | Callback function to act on matches. Takes the arguments `matcher`, `doc`, `i` and `matches`. ~~Optional[Callable[[Matcher, Doc, int, List[tuple], Any]]~~ |
| `greedy` 3 | Optional filter for greedy matches. Can either be `"FIRST"` or `"LONGEST"`. ~~Optional[str]~~ |
-## Matcher.remove {#remove tag="method" new="2"}
+## Matcher.remove {id="remove",tag="method",version="2"}
Remove a rule from the matcher. A `KeyError` is raised if the match ID does not
exist.
@@ -234,7 +251,7 @@ exist.
| ----- | --------------------------------- |
| `key` | The ID of the match rule. ~~str~~ |
-## Matcher.get {#get tag="method" new="2"}
+## Matcher.get {id="get",tag="method",version="2"}
Retrieve the pattern stored for a key. Returns the rule as an
`(on_match, patterns)` tuple containing the callback and available patterns.
diff --git a/website/docs/api/morphologizer.md b/website/docs/api/morphologizer.mdx
similarity index 93%
rename from website/docs/api/morphologizer.md
rename to website/docs/api/morphologizer.mdx
index 434c56833..f097f2ae3 100644
--- a/website/docs/api/morphologizer.md
+++ b/website/docs/api/morphologizer.mdx
@@ -2,7 +2,7 @@
title: Morphologizer
tag: class
source: spacy/pipeline/morphologizer.pyx
-new: 3
+version: 3
teaser: 'Pipeline component for predicting morphological features'
api_base_class: /api/tagger
api_string_name: morphologizer
@@ -15,7 +15,7 @@ coarse-grained POS tags following the Universal Dependencies
[FEATS](https://universaldependencies.org/format.html#morphological-annotation)
annotation guidelines.
-## Assigned Attributes {#assigned-attributes}
+## Assigned Attributes {id="assigned-attributes"}
Predictions are saved to `Token.morph` and `Token.pos`.
@@ -25,7 +25,7 @@ Predictions are saved to `Token.morph` and `Token.pos`.
| `Token.pos_` | The UPOS part of speech. ~~str~~ |
| `Token.morph` | Morphological features. ~~MorphAnalysis~~ |
-## Config and implementation {#config}
+## Config and implementation {id="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
@@ -53,7 +53,7 @@ architectures and their arguments and hyperparameters.
%%GITHUB_SPACY/spacy/pipeline/morphologizer.pyx
```
-## Morphologizer.\_\_init\_\_ {#init tag="method"}
+## Morphologizer.\_\_init\_\_ {id="init",tag="method"}
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
@@ -97,7 +97,7 @@ annotation `C=E|X=Y`):
| `extend` 3.2 | Whether existing feature types (whose values may or may not be overwritten depending on `overwrite`) are preserved. Defaults to `False`. ~~bool~~ |
| `scorer` 3.2 | The scoring method. Defaults to [`Scorer.score_token_attr`](/api/scorer#score_token_attr) for the attributes `"pos"` and `"morph"` and [`Scorer.score_token_attr_per_feat`](/api/scorer#score_token_attr_per_feat) for the attribute `"morph"`. ~~Optional[Callable]~~ |
-## Morphologizer.\_\_call\_\_ {#call tag="method"}
+## Morphologizer.\_\_call\_\_ {id="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
@@ -120,7 +120,7 @@ delegate to the [`predict`](/api/morphologizer#predict) and
| `doc` | The document to process. ~~Doc~~ |
| **RETURNS** | The processed document. ~~Doc~~ |
-## Morphologizer.pipe {#pipe tag="method"}
+## Morphologizer.pipe {id="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
@@ -144,13 +144,13 @@ applied to the `Doc` in order. Both [`__call__`](/api/morphologizer#call) and
| `batch_size` | The number of documents to buffer. Defaults to `128`. ~~int~~ |
| **YIELDS** | The processed documents in order. ~~Doc~~ |
-## Morphologizer.initialize {#initialize tag="method"}
+## Morphologizer.initialize {id="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) and lets you customize
@@ -162,7 +162,7 @@ config.
>
> ```python
> morphologizer = nlp.add_pipe("morphologizer")
-> morphologizer.initialize(lambda: [], nlp=nlp)
+> morphologizer.initialize(lambda: examples, nlp=nlp)
> ```
>
> ```ini
@@ -176,12 +176,12 @@ config.
| Name | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `get_examples` | Function that returns gold-standard annotations in the form of [`Example`](/api/example) objects. ~~Callable[[], Iterable[Example]]~~ |
+| `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]~~ |
| `labels` | The label information to add to the component, as provided by the [`label_data`](#label_data) property after initialization. To generate a reusable JSON file from your data, you should run the [`init labels`](/api/cli#init-labels) command. If no labels are provided, the `get_examples` callback is used to extract the labels from the data, which may be a lot slower. ~~Optional[dict]~~ |
-## Morphologizer.predict {#predict tag="method"}
+## Morphologizer.predict {id="predict",tag="method"}
Apply the component's model to a batch of [`Doc`](/api/doc) objects, without
modifying them.
@@ -198,7 +198,7 @@ modifying them.
| `docs` | The documents to predict. ~~Iterable[Doc]~~ |
| **RETURNS** | The model's prediction for each document. |
-## Morphologizer.set_annotations {#set_annotations tag="method"}
+## Morphologizer.set_annotations {id="set_annotations",tag="method"}
Modify a batch of [`Doc`](/api/doc) objects, using pre-computed scores.
@@ -215,7 +215,7 @@ Modify a batch of [`Doc`](/api/doc) objects, using pre-computed scores.
| `docs` | The documents to modify. ~~Iterable[Doc]~~ |
| `scores` | The scores to set, produced by `Morphologizer.predict`. |
-## Morphologizer.update {#update tag="method"}
+## Morphologizer.update {id="update",tag="method"}
Learn from a batch of [`Example`](/api/example) objects containing the
predictions and gold-standard annotations, and update the component's model.
@@ -239,7 +239,7 @@ Delegates to [`predict`](/api/morphologizer#predict) and
| `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]~~ |
-## Morphologizer.get_loss {#get_loss tag="method"}
+## Morphologizer.get_loss {id="get_loss",tag="method"}
Find the loss and gradient of loss for the batch of documents and their
predicted scores.
@@ -258,7 +258,7 @@ predicted scores.
| `scores` | Scores representing the model's predictions. |
| **RETURNS** | The loss and the gradient, i.e. `(loss, gradient)`. ~~Tuple[float, float]~~ |
-## Morphologizer.create_optimizer {#create_optimizer tag="method"}
+## Morphologizer.create_optimizer {id="create_optimizer",tag="method"}
Create an optimizer for the pipeline component.
@@ -273,7 +273,7 @@ Create an optimizer for the pipeline component.
| ----------- | ---------------------------- |
| **RETURNS** | The optimizer. ~~Optimizer~~ |
-## Morphologizer.use_params {#use_params tag="method, contextmanager"}
+## Morphologizer.use_params {id="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.
@@ -290,7 +290,7 @@ context, the original parameters are restored.
| -------- | -------------------------------------------------- |
| `params` | The parameter values to use in the model. ~~dict~~ |
-## Morphologizer.add_label {#add_label tag="method"}
+## Morphologizer.add_label {id="add_label",tag="method"}
Add a new label to the pipe. If the `Morphologizer` should set annotations for
both `pos` and `morph`, the label should include the UPOS as the feature `POS`.
@@ -313,7 +313,7 @@ will be automatically added to the model, and the output dimension will be
| `label` | The label to add. ~~str~~ |
| **RETURNS** | `0` if the label is already present, otherwise `1`. ~~int~~ |
-## Morphologizer.to_disk {#to_disk tag="method"}
+## Morphologizer.to_disk {id="to_disk",tag="method"}
Serialize the pipe to disk.
@@ -330,7 +330,7 @@ Serialize the pipe to disk.
| _keyword-only_ | |
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
-## Morphologizer.from_disk {#from_disk tag="method"}
+## Morphologizer.from_disk {id="from_disk",tag="method"}
Load the pipe from disk. Modifies the object in place and returns it.
@@ -348,7 +348,7 @@ Load the pipe from disk. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The modified `Morphologizer` object. ~~Morphologizer~~ |
-## Morphologizer.to_bytes {#to_bytes tag="method"}
+## Morphologizer.to_bytes {id="to_bytes",tag="method"}
> #### Example
>
@@ -365,7 +365,7 @@ Serialize the pipe to a bytestring.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The serialized form of the `Morphologizer` object. ~~bytes~~ |
-## Morphologizer.from_bytes {#from_bytes tag="method"}
+## Morphologizer.from_bytes {id="from_bytes",tag="method"}
Load the pipe from a bytestring. Modifies the object in place and returns it.
@@ -384,7 +384,7 @@ Load the pipe from a bytestring. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The `Morphologizer` object. ~~Morphologizer~~ |
-## Morphologizer.labels {#labels tag="property"}
+## Morphologizer.labels {id="labels",tag="property"}
The labels currently added to the component in the Universal Dependencies
[FEATS](https://universaldependencies.org/format.html#morphological-annotation)
@@ -403,7 +403,7 @@ coarse-grained POS as the feature `POS`.
| ----------- | ------------------------------------------------------ |
| **RETURNS** | The labels added to the component. ~~Tuple[str, ...]~~ |
-## Morphologizer.label_data {#label_data tag="property" new="3"}
+## Morphologizer.label_data {id="label_data",tag="property",version="3"}
The labels currently added to the component and their internal meta information.
This is the data generated by [`init labels`](/api/cli#init-labels) and used by
@@ -421,7 +421,7 @@ model with a pre-defined label set.
| ----------- | ----------------------------------------------- |
| **RETURNS** | The label data added to the component. ~~dict~~ |
-## Serialization fields {#serialization-fields}
+## Serialization fields {id="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
diff --git a/website/docs/api/morphology.md b/website/docs/api/morphology.mdx
similarity index 89%
rename from website/docs/api/morphology.md
rename to website/docs/api/morphology.mdx
index 20fcd1a40..68d80b814 100644
--- a/website/docs/api/morphology.md
+++ b/website/docs/api/morphology.mdx
@@ -10,7 +10,7 @@ morphological analysis, so queries of morphological attributes are delegated to
this class. See [`MorphAnalysis`](/api/morphology#morphanalysis) for the
container storing a single morphological analysis.
-## Morphology.\_\_init\_\_ {#init tag="method"}
+## Morphology.\_\_init\_\_ {id="init",tag="method"}
Create a `Morphology` object.
@@ -26,7 +26,7 @@ Create a `Morphology` object.
| --------- | --------------------------------- |
| `strings` | The string store. ~~StringStore~~ |
-## Morphology.add {#add tag="method"}
+## Morphology.add {id="add",tag="method"}
Insert a morphological analysis in the morphology table, if not already present.
The morphological analysis may be provided in the Universal Dependencies
@@ -46,7 +46,7 @@ new analysis.
| ---------- | ------------------------------------------------ |
| `features` | The morphological features. ~~Union[Dict, str]~~ |
-## Morphology.get {#get tag="method"}
+## Morphology.get {id="get",tag="method"}
> #### Example
>
@@ -64,7 +64,7 @@ string for the hash of the morphological analysis.
| ------- | ----------------------------------------------- |
| `morph` | The hash of the morphological analysis. ~~int~~ |
-## Morphology.feats_to_dict {#feats_to_dict tag="staticmethod"}
+## Morphology.feats_to_dict {id="feats_to_dict",tag="staticmethod"}
Convert a string
[FEATS](https://universaldependencies.org/format.html#morphological-annotation)
@@ -84,7 +84,7 @@ tag map.
| `feats` | The morphological features in Universal Dependencies [FEATS](https://universaldependencies.org/format.html#morphological-annotation) format. ~~str~~ |
| **RETURNS** | The morphological features as a dictionary. ~~Dict[str, str]~~ |
-## Morphology.dict_to_feats {#dict_to_feats tag="staticmethod"}
+## Morphology.dict_to_feats {id="dict_to_feats",tag="staticmethod"}
Convert a dictionary of features and values to a string
[FEATS](https://universaldependencies.org/format.html#morphological-annotation)
@@ -103,19 +103,19 @@ representation.
| `feats_dict` | The morphological features as a dictionary. ~~Dict[str, str]~~ |
| **RETURNS** | The morphological features in Universal Dependencies [FEATS](https://universaldependencies.org/format.html#morphological-annotation) format. ~~str~~ |
-## Attributes {#attributes}
+## Attributes {id="attributes"}
-| Name | Description |
-| ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `FEATURE_SEP` | The [FEATS](https://universaldependencies.org/format.html#morphological-annotation) feature separator. Default is `|`. ~~str~~ |
-| `FIELD_SEP` | The [FEATS](https://universaldependencies.org/format.html#morphological-annotation) field separator. Default is `=`. ~~str~~ |
-| `VALUE_SEP` | The [FEATS](https://universaldependencies.org/format.html#morphological-annotation) value separator. Default is `,`. ~~str~~ |
+| Name | Description |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `FEATURE_SEP` | The [FEATS](https://universaldependencies.org/format.html#morphological-annotation) feature separator. Default is `\|`. ~~str~~ |
+| `FIELD_SEP` | The [FEATS](https://universaldependencies.org/format.html#morphological-annotation) field separator. Default is `=`. ~~str~~ |
+| `VALUE_SEP` | The [FEATS](https://universaldependencies.org/format.html#morphological-annotation) value separator. Default is `,`. ~~str~~ |
-## MorphAnalysis {#morphanalysis tag="class" source="spacy/tokens/morphanalysis.pyx"}
+## MorphAnalysis {id="morphanalysis",tag="class",source="spacy/tokens/morphanalysis.pyx"}
Stores a single morphological analysis.
-### MorphAnalysis.\_\_init\_\_ {#morphanalysis-init tag="method"}
+### MorphAnalysis.\_\_init\_\_ {id="morphanalysis-init",tag="method"}
Initialize a MorphAnalysis object from a Universal Dependencies
[FEATS](https://universaldependencies.org/format.html#morphological-annotation)
@@ -135,7 +135,7 @@ string or a dictionary of morphological features.
| `vocab` | The vocab. ~~Vocab~~ |
| `features` | The morphological features. ~~Union[Dict[str, str], str]~~ |
-### MorphAnalysis.\_\_contains\_\_ {#morphanalysis-contains tag="method"}
+### MorphAnalysis.\_\_contains\_\_ {id="morphanalysis-contains",tag="method"}
Whether a feature/value pair is in the analysis.
@@ -151,7 +151,7 @@ Whether a feature/value pair is in the analysis.
| ----------- | --------------------------------------------- |
| **RETURNS** | A feature/value pair in the analysis. ~~str~~ |
-### MorphAnalysis.\_\_iter\_\_ {#morphanalysis-iter tag="method"}
+### MorphAnalysis.\_\_iter\_\_ {id="morphanalysis-iter",tag="method"}
Iterate over the feature/value pairs in the analysis.
@@ -167,7 +167,7 @@ Iterate over the feature/value pairs in the analysis.
| ---------- | --------------------------------------------- |
| **YIELDS** | A feature/value pair in the analysis. ~~str~~ |
-### MorphAnalysis.\_\_len\_\_ {#morphanalysis-len tag="method"}
+### MorphAnalysis.\_\_len\_\_ {id="morphanalysis-len",tag="method"}
Returns the number of features in the analysis.
@@ -183,7 +183,7 @@ Returns the number of features in the analysis.
| ----------- | ----------------------------------------------- |
| **RETURNS** | The number of features in the analysis. ~~int~~ |
-### MorphAnalysis.\_\_str\_\_ {#morphanalysis-str tag="method"}
+### MorphAnalysis.\_\_str\_\_ {id="morphanalysis-str",tag="method"}
Returns the morphological analysis in the Universal Dependencies
[FEATS](https://universaldependencies.org/format.html#morphological-annotation)
@@ -201,7 +201,7 @@ string format.
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **RETURNS** | The analysis in the Universal Dependencies [FEATS](https://universaldependencies.org/format.html#morphological-annotation) format. ~~str~~ |
-### MorphAnalysis.get {#morphanalysis-get tag="method"}
+### MorphAnalysis.get {id="morphanalysis-get",tag="method"}
Retrieve values for a feature by field.
@@ -218,7 +218,7 @@ Retrieve values for a feature by field.
| `field` | The field to retrieve. ~~str~~ |
| **RETURNS** | A list of the individual features. ~~List[str]~~ |
-### MorphAnalysis.to_dict {#morphanalysis-to_dict tag="method"}
+### MorphAnalysis.to_dict {id="morphanalysis-to_dict",tag="method"}
Produce a dict representation of the analysis, in the same format as the tag
map.
@@ -235,7 +235,7 @@ map.
| ----------- | ----------------------------------------------------------- |
| **RETURNS** | The dict representation of the analysis. ~~Dict[str, str]~~ |
-### MorphAnalysis.from_id {#morphanalysis-from_id tag="classmethod"}
+### MorphAnalysis.from_id {id="morphanalysis-from_id",tag="classmethod"}
Create a morphological analysis from a given hash ID.
diff --git a/website/docs/api/phrasematcher.md b/website/docs/api/phrasematcher.mdx
similarity index 88%
rename from website/docs/api/phrasematcher.md
rename to website/docs/api/phrasematcher.mdx
index 2cef9ac2a..14ccefb77 100644
--- a/website/docs/api/phrasematcher.md
+++ b/website/docs/api/phrasematcher.mdx
@@ -3,7 +3,7 @@ title: PhraseMatcher
teaser: Match sequences of tokens, based on documents
tag: class
source: spacy/matcher/phrasematcher.pyx
-new: 2
+version: 2
---
The `PhraseMatcher` lets you efficiently match large terminology lists. While
@@ -12,7 +12,7 @@ descriptions, the `PhraseMatcher` accepts match patterns in the form of `Doc`
objects. See the [usage guide](/usage/rule-based-matching#phrasematcher) for
examples.
-## PhraseMatcher.\_\_init\_\_ {#init tag="method"}
+## PhraseMatcher.\_\_init\_\_ {id="init",tag="method"}
Create the rule-based `PhraseMatcher`. Setting a different `attr` to match on
will change the token attributes that will be compared to determine a match. By
@@ -36,13 +36,13 @@ be shown.
> matcher = PhraseMatcher(nlp.vocab)
> ```
-| Name | Description |
-| --------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `vocab` | The vocabulary object, which must be shared with the documents the matcher will operate on. ~~Vocab~~ |
-| `attr` 2.1 | The token attribute to match on. Defaults to `ORTH`, i.e. the verbatim token text. ~~Union[int, str]~~ |
-| `validate` 2.1 | Validate patterns added to the matcher. ~~bool~~ |
+| Name | Description |
+| ---------- | ------------------------------------------------------------------------------------------------------ |
+| `vocab` | The vocabulary object, which must be shared with the documents the matcher will operate on. ~~Vocab~~ |
+| `attr` | The token attribute to match on. Defaults to `ORTH`, i.e. the verbatim token text. ~~Union[int, str]~~ |
+| `validate` | Validate patterns added to the matcher. ~~bool~~ |
-## PhraseMatcher.\_\_call\_\_ {#call tag="method"}
+## PhraseMatcher.\_\_call\_\_ {id="call",tag="method"}
Find all token sequences matching the supplied patterns on the `Doc` or `Span`.
@@ -76,7 +76,7 @@ match_id_string = nlp.vocab.strings[match_id]
-## PhraseMatcher.\_\_len\_\_ {#len tag="method"}
+## PhraseMatcher.\_\_len\_\_ {id="len",tag="method"}
Get the number of rules added to the matcher. Note that this only returns the
number of rules (identical with the number of IDs), not the number of individual
@@ -95,7 +95,7 @@ patterns.
| ----------- | ---------------------------- |
| **RETURNS** | The number of rules. ~~int~~ |
-## PhraseMatcher.\_\_contains\_\_ {#contains tag="method"}
+## PhraseMatcher.\_\_contains\_\_ {id="contains",tag="method"}
Check whether the matcher contains rules for a match ID.
@@ -113,7 +113,7 @@ Check whether the matcher contains rules for a match ID.
| `key` | The match ID. ~~str~~ |
| **RETURNS** | Whether the matcher contains rules for this match ID. ~~bool~~ |
-## PhraseMatcher.add {#add tag="method"}
+## PhraseMatcher.add {id="add",tag="method"}
Add a rule to the matcher, consisting of an ID key, one or more patterns, and a
callback function to act on the matches. The callback function will receive the
@@ -155,7 +155,7 @@ patterns = [nlp("health care reform"), nlp("healthcare reform")]
| _keyword-only_ | |
| `on_match` | Callback function to act on matches. Takes the arguments `matcher`, `doc`, `i` and `matches`. ~~Optional[Callable[[Matcher, Doc, int, List[tuple], Any]]~~ |
-## PhraseMatcher.remove {#remove tag="method" new="2.2"}
+## PhraseMatcher.remove {id="remove",tag="method",version="2.2"}
Remove a rule from the matcher by match ID. A `KeyError` is raised if the key
does not exist.
diff --git a/website/docs/api/pipe.md b/website/docs/api/pipe.mdx
similarity index 93%
rename from website/docs/api/pipe.md
rename to website/docs/api/pipe.mdx
index 263942e3e..c2777edf0 100644
--- a/website/docs/api/pipe.md
+++ b/website/docs/api/pipe.mdx
@@ -12,7 +12,7 @@ spaCy pipeline. See the docs on
[writing trainable components](/usage/processing-pipelines#trainable-components)
for how to use the `TrainablePipe` base class to implement custom components.
-
+{/* TODO: Pipe vs TrainablePipe, check methods below (all renamed to TrainablePipe for now) */}
> #### Why is it implemented in Cython?
>
@@ -27,7 +27,7 @@ for how to use the `TrainablePipe` base class to implement custom components.
%%GITHUB_SPACY/spacy/pipeline/trainable_pipe.pyx
```
-## TrainablePipe.\_\_init\_\_ {#init tag="method"}
+## TrainablePipe.\_\_init\_\_ {id="init",tag="method"}
> #### Example
>
@@ -54,7 +54,7 @@ shortcut for this and instantiate the component using its string name and
| `name` | String name of the component instance. Used to add entries to the `losses` during training. ~~str~~ |
| `**cfg` | Additional config parameters and settings. Will be available as the dictionary `cfg` and is serialized with the component. |
-## TrainablePipe.\_\_call\_\_ {#call tag="method"}
+## TrainablePipe.\_\_call\_\_ {id="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
@@ -77,7 +77,7 @@ and all pipeline components are applied to the `Doc` in order. Both
| `doc` | The document to process. ~~Doc~~ |
| **RETURNS** | The processed document. ~~Doc~~ |
-## TrainablePipe.pipe {#pipe tag="method"}
+## TrainablePipe.pipe {id="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
@@ -100,7 +100,7 @@ applied to the `Doc` in order. Both [`__call__`](/api/pipe#call) and
| `batch_size` | The number of documents to buffer. Defaults to `128`. ~~int~~ |
| **YIELDS** | The processed documents in order. ~~Doc~~ |
-## TrainablePipe.set_error_handler {#set_error_handler tag="method" new="3"}
+## TrainablePipe.set_error_handler {id="set_error_handler",tag="method",version="3"}
Define a callback that will be invoked when an error is thrown during processing
of one or more documents with either [`__call__`](/api/pipe#call) or
@@ -122,7 +122,7 @@ processed, and the original error.
| --------------- | -------------------------------------------------------------------------------------------------------------- |
| `error_handler` | A function that performs custom error handling. ~~Callable[[str, Callable[[Doc], Doc], List[Doc], Exception]~~ |
-## TrainablePipe.get_error_handler {#get_error_handler tag="method" new="3"}
+## TrainablePipe.get_error_handler {id="get_error_handler",tag="method",version="3"}
Retrieve the callback that performs error handling for this component's
[`__call__`](/api/pipe#call) and [`pipe`](/api/pipe#pipe) methods. If no custom
@@ -141,7 +141,7 @@ returned that simply reraises the exception.
| ----------- | ---------------------------------------------------------------------------------------------------------------- |
| **RETURNS** | The function that performs custom error handling. ~~Callable[[str, Callable[[Doc], Doc], List[Doc], Exception]~~ |
-## TrainablePipe.initialize {#initialize tag="method" new="3"}
+## TrainablePipe.initialize {id="initialize",tag="method",version="3"}
Initialize the component for training. `get_examples` should be a function that
returns an iterable of [`Example`](/api/example) objects. The data examples are
@@ -171,7 +171,7 @@ This method was previously called `begin_training`.
| _keyword-only_ | |
| `nlp` | The current `nlp` object. Defaults to `None`. ~~Optional[Language]~~ |
-## TrainablePipe.predict {#predict tag="method"}
+## TrainablePipe.predict {id="predict",tag="method"}
Apply the component's model to a batch of [`Doc`](/api/doc) objects, without
modifying them.
@@ -194,7 +194,7 @@ This method needs to be overwritten with your own custom `predict` method.
| `docs` | The documents to predict. ~~Iterable[Doc]~~ |
| **RETURNS** | The model's prediction for each document. |
-## TrainablePipe.set_annotations {#set_annotations tag="method"}
+## TrainablePipe.set_annotations {id="set_annotations",tag="method"}
Modify a batch of [`Doc`](/api/doc) objects, using pre-computed scores.
@@ -218,7 +218,7 @@ method.
| `docs` | The documents to modify. ~~Iterable[Doc]~~ |
| `scores` | The scores to set, produced by `Tagger.predict`. |
-## TrainablePipe.update {#update tag="method"}
+## TrainablePipe.update {id="update",tag="method"}
Learn from a batch of [`Example`](/api/example) objects containing the
predictions and gold-standard annotations, and update the component's model.
@@ -240,7 +240,7 @@ predictions and gold-standard annotations, and update the component's model.
| `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]~~ |
-## TrainablePipe.rehearse {#rehearse tag="method,experimental" new="3"}
+## TrainablePipe.rehearse {id="rehearse",tag="method,experimental",version="3"}
Perform a "rehearsal" update from a batch of data. Rehearsal updates teach the
current model to make predictions similar to an initial model, to try to address
@@ -262,7 +262,7 @@ the "catastrophic forgetting" problem. This feature is experimental.
| `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]~~ |
-## TrainablePipe.get_loss {#get_loss tag="method"}
+## TrainablePipe.get_loss {id="get_loss",tag="method"}
Find the loss and gradient of loss for the batch of documents and their
predicted scores.
@@ -287,7 +287,7 @@ This method needs to be overwritten with your own custom `get_loss` method.
| `scores` | Scores representing the model's predictions. |
| **RETURNS** | The loss and the gradient, i.e. `(loss, gradient)`. ~~Tuple[float, float]~~ |
-## TrainablePipe.score {#score tag="method" new="3"}
+## TrainablePipe.score {id="score",tag="method",version="3"}
Score a batch of examples.
@@ -304,7 +304,7 @@ Score a batch of examples.
| `\*\*kwargs` | Any additional settings to pass on to the scorer. ~~Any~~ |
| **RETURNS** | The scores, e.g. produced by the [`Scorer`](/api/scorer). ~~Dict[str, Union[float, Dict[str, float]]]~~ |
-## TrainablePipe.create_optimizer {#create_optimizer tag="method"}
+## TrainablePipe.create_optimizer {id="create_optimizer",tag="method"}
Create an optimizer for the pipeline component. Defaults to
[`Adam`](https://thinc.ai/docs/api-optimizers#adam) with default settings.
@@ -320,7 +320,7 @@ Create an optimizer for the pipeline component. Defaults to
| ----------- | ---------------------------- |
| **RETURNS** | The optimizer. ~~Optimizer~~ |
-## TrainablePipe.use_params {#use_params tag="method, contextmanager"}
+## TrainablePipe.use_params {id="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.
@@ -337,7 +337,7 @@ context, the original parameters are restored.
| -------- | -------------------------------------------------- |
| `params` | The parameter values to use in the model. ~~dict~~ |
-## TrainablePipe.finish_update {#finish_update tag="method"}
+## TrainablePipe.finish_update {id="finish_update",tag="method"}
Update parameters using the current parameter gradients. Defaults to calling
[`self.model.finish_update`](https://thinc.ai/docs/api-model#finish_update).
@@ -355,7 +355,7 @@ Update parameters using the current parameter gradients. Defaults to calling
| ----- | ------------------------------------- |
| `sgd` | An optimizer. ~~Optional[Optimizer]~~ |
-## TrainablePipe.add_label {#add_label tag="method"}
+## TrainablePipe.add_label {id="add_label",tag="method"}
> #### Example
>
@@ -390,7 +390,7 @@ case, all labels found in the sample will be automatically added to the model,
and the output dimension will be
[inferred](/usage/layers-architectures#thinc-shape-inference) automatically.
-## TrainablePipe.is_resizable {#is_resizable tag="property"}
+## TrainablePipe.is_resizable {id="is_resizable",tag="property"}
> #### Example
>
@@ -421,7 +421,7 @@ as an attribute to the component's model.
| ----------- | ---------------------------------------------------------------------------------------------- |
| **RETURNS** | Whether or not the output dimension of the model can be changed after initialization. ~~bool~~ |
-## TrainablePipe.set_output {#set_output tag="method"}
+## TrainablePipe.set_output {id="set_output",tag="method"}
Change the output dimension of the component's model. If the component is not
[resizable](#is_resizable), this method will raise a `NotImplementedError`. If a
@@ -441,7 +441,7 @@ care should be taken to avoid the "catastrophic forgetting" problem.
| ---- | --------------------------------- |
| `nO` | The new output dimension. ~~int~~ |
-## TrainablePipe.to_disk {#to_disk tag="method"}
+## TrainablePipe.to_disk {id="to_disk",tag="method"}
Serialize the pipe to disk.
@@ -458,7 +458,7 @@ Serialize the pipe to disk.
| _keyword-only_ | |
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
-## TrainablePipe.from_disk {#from_disk tag="method"}
+## TrainablePipe.from_disk {id="from_disk",tag="method"}
Load the pipe from disk. Modifies the object in place and returns it.
@@ -476,7 +476,7 @@ Load the pipe from disk. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The modified pipe. ~~TrainablePipe~~ |
-## TrainablePipe.to_bytes {#to_bytes tag="method"}
+## TrainablePipe.to_bytes {id="to_bytes",tag="method"}
> #### Example
>
@@ -493,7 +493,7 @@ Serialize the pipe to a bytestring.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The serialized form of the pipe. ~~bytes~~ |
-## TrainablePipe.from_bytes {#from_bytes tag="method"}
+## TrainablePipe.from_bytes {id="from_bytes",tag="method"}
Load the pipe from a bytestring. Modifies the object in place and returns it.
@@ -512,7 +512,7 @@ Load the pipe from a bytestring. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The pipe. ~~TrainablePipe~~ |
-## Attributes {#attributes}
+## Attributes {id="attributes"}
| Name | Description |
| ------- | --------------------------------------------------------------------------------------------------------------------------------- |
@@ -521,7 +521,7 @@ Load the pipe from a bytestring. Modifies the object in place and returns it.
| `name` | The name of the component instance in the pipeline. Can be used in the losses. ~~str~~ |
| `cfg` | Keyword arguments passed to [`TrainablePipe.__init__`](/api/pipe#init). Will be serialized with the component. ~~Dict[str, Any]~~ |
-## Serialization fields {#serialization-fields}
+## Serialization fields {id="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
diff --git a/website/docs/api/pipeline-functions.md b/website/docs/api/pipeline-functions.mdx
similarity index 76%
rename from website/docs/api/pipeline-functions.md
rename to website/docs/api/pipeline-functions.mdx
index ff19d3e71..545ace2f2 100644
--- a/website/docs/api/pipeline-functions.md
+++ b/website/docs/api/pipeline-functions.mdx
@@ -7,9 +7,10 @@ menu:
- ['merge_entities', 'merge_entities']
- ['merge_subtokens', 'merge_subtokens']
- ['token_splitter', 'token_splitter']
+ - ['doc_cleaner', 'doc_cleaner']
---
-## merge_noun_chunks {#merge_noun_chunks tag="function"}
+## merge_noun_chunks {id="merge_noun_chunks",tag="function"}
Merge noun chunks into a single token. Also available via the string name
`"merge_noun_chunks"`.
@@ -39,7 +40,7 @@ all other components.
| `doc` | The `Doc` object to process, e.g. the `Doc` in the pipeline. ~~Doc~~ |
| **RETURNS** | The modified `Doc` with merged noun chunks. ~~Doc~~ |
-## merge_entities {#merge_entities tag="function"}
+## merge_entities {id="merge_entities",tag="function"}
Merge named entities into a single token. Also available via the string name
`"merge_entities"`.
@@ -69,7 +70,7 @@ components to the end of the pipeline and after all other components.
| `doc` | The `Doc` object to process, e.g. the `Doc` in the pipeline. ~~Doc~~ |
| **RETURNS** | The modified `Doc` with merged entities. ~~Doc~~ |
-## merge_subtokens {#merge_subtokens tag="function" new="2.1"}
+## merge_subtokens {id="merge_subtokens",tag="function",version="2.1"}
Merge subtokens into a single token. Also available via the string name
`"merge_subtokens"`. As of v2.1, the parser is able to predict "subtokens" that
@@ -109,7 +110,7 @@ end of the pipeline and after all other components.
| `label` | The subtoken dependency label. Defaults to `"subtok"`. ~~str~~ |
| **RETURNS** | The modified `Doc` with merged subtokens. ~~Doc~~ |
-## token_splitter {#token_splitter tag="function" new="3.0"}
+## token_splitter {id="token_splitter",tag="function",version="3.0"}
Split tokens longer than a minimum length into shorter tokens. Intended for use
with transformer pipelines where long spaCy tokens lead to input text that
@@ -131,7 +132,7 @@ exceed the transformer model max length.
| `split_length` | The length of the split tokens. Defaults to `5`. ~~int~~ |
| **RETURNS** | The modified `Doc` with the split tokens. ~~Doc~~ |
-## doc_cleaner {#doc_cleaner tag="function" new="3.2.1"}
+## doc_cleaner {id="doc_cleaner",tag="function",version="3.2.1"}
Clean up `Doc` attributes. Intended for use at the end of pipelines with
`tok2vec` or `transformer` pipeline components that store tensors and other
@@ -152,3 +153,36 @@ 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 {id="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-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
+[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 any matching spans removed. ~~Doc~~ |
diff --git a/website/docs/api/scorer.md b/website/docs/api/scorer.mdx
similarity index 78%
rename from website/docs/api/scorer.md
rename to website/docs/api/scorer.mdx
index 8dbe3b276..6f0c95f6f 100644
--- a/website/docs/api/scorer.md
+++ b/website/docs/api/scorer.mdx
@@ -10,7 +10,7 @@ The `Scorer` computes evaluation scores. It's typically created by
provides a number of evaluation methods for evaluating [`Token`](/api/token) and
[`Doc`](/api/doc) attributes.
-## Scorer.\_\_init\_\_ {#init tag="method"}
+## Scorer.\_\_init\_\_ {id="init",tag="method"}
Create a new `Scorer`.
@@ -35,7 +35,7 @@ Create a new `Scorer`.
| _keyword-only_ | |
| `\*\*kwargs` | Any additional settings to pass on to the individual scoring methods. ~~Any~~ |
-## Scorer.score {#score tag="method"}
+## Scorer.score {id="score",tag="method"}
Calculate the scores for a list of [`Example`](/api/example) objects using the
scoring methods provided by the components in the pipeline.
@@ -72,11 +72,11 @@ core pipeline components, the individual score names start with the `Token` or
| `examples` | The `Example` objects holding both the predictions and the correct gold-standard annotations. ~~Iterable[Example]~~ |
| **RETURNS** | A dictionary of scores. ~~Dict[str, Union[float, Dict[str, float]]]~~ |
-## Scorer.score_tokenization {#score_tokenization tag="staticmethod" new="3"}
+## Scorer.score_tokenization {id="score_tokenization",tag="staticmethod",version="3"}
Scores the tokenization:
-- `token_acc`: number of correct tokens / number of gold tokens
+- `token_acc`: number of correct tokens / number of predicted tokens
- `token_p`, `token_r`, `token_f`: precision, recall and F-score for token
character spans
@@ -93,7 +93,7 @@ Docs with `has_unknown_spaces` are skipped during scoring.
| `examples` | The `Example` objects holding both the predictions and the correct gold-standard annotations. ~~Iterable[Example]~~ |
| **RETURNS** | `Dict` | A dictionary containing the scores `token_acc`, `token_p`, `token_r`, `token_f`. ~~Dict[str, float]]~~ |
-## Scorer.score_token_attr {#score_token_attr tag="staticmethod" new="3"}
+## Scorer.score_token_attr {id="score_token_attr",tag="staticmethod",version="3"}
Scores a single token attribute. Tokens with missing values in the reference doc
are skipped during scoring.
@@ -114,7 +114,7 @@ are skipped during scoring.
| `missing_values` | Attribute values to treat as missing annotation in the reference annotation. Defaults to `{0, None, ""}`. ~~Set[Any]~~ |
| **RETURNS** | A dictionary containing the score `{attr}_acc`. ~~Dict[str, float]~~ |
-## Scorer.score_token_attr_per_feat {#score_token_attr_per_feat tag="staticmethod" new="3"}
+## Scorer.score_token_attr_per_feat {id="score_token_attr_per_feat",tag="staticmethod",version="3"}
Scores a single token attribute per feature for a token attribute in the
Universal Dependencies
@@ -138,7 +138,7 @@ scoring.
| `missing_values` | Attribute values to treat as missing annotation in the reference annotation. Defaults to `{0, None, ""}`. ~~Set[Any]~~ |
| **RETURNS** | A dictionary containing the micro PRF scores under the key `{attr}_micro_p/r/f` and the per-feature PRF scores under `{attr}_per_feat`. ~~Dict[str, Dict[str, float]]~~ |
-## Scorer.score_spans {#score_spans tag="staticmethod" new="3"}
+## Scorer.score_spans {id="score_spans",tag="staticmethod",version="3"}
Returns PRF scores for labeled or unlabeled spans.
@@ -160,7 +160,7 @@ Returns PRF scores for labeled or unlabeled spans.
| `allow_overlap` | Defaults to `False`. Whether or not to allow overlapping spans. If set to `False`, the alignment will automatically resolve conflicts. ~~bool~~ |
| **RETURNS** | A dictionary containing the PRF scores under the keys `{attr}_p`, `{attr}_r`, `{attr}_f` and the per-type PRF scores under `{attr}_per_type`. ~~Dict[str, Union[float, Dict[str, float]]]~~ |
-## Scorer.score_deps {#score_deps tag="staticmethod" new="3"}
+## Scorer.score_deps {id="score_deps",tag="staticmethod",version="3"}
Calculate the UAS, LAS, and LAS per type scores for dependency parses. Tokens
with missing values for the `attr` (typically `dep`) are skipped during scoring.
@@ -194,7 +194,7 @@ with missing values for the `attr` (typically `dep`) are skipped during scoring.
| `missing_values` | Attribute values to treat as missing annotation in the reference annotation. Defaults to `{0, None, ""}`. ~~Set[Any]~~ |
| **RETURNS** | A dictionary containing the scores: `{attr}_uas`, `{attr}_las`, and `{attr}_las_per_type`. ~~Dict[str, Union[float, Dict[str, float]]]~~ |
-## Scorer.score_cats {#score_cats tag="staticmethod" new="3"}
+## Scorer.score_cats {id="score_cats",tag="staticmethod",version="3"}
Calculate PRF and ROC AUC scores for a doc-level attribute that is a dict
containing scores for each label like `Doc.cats`. The returned dictionary
@@ -229,18 +229,19 @@ The reported `{attr}_score` depends on the classification properties:
> print(scores["cats_macro_auc"])
> ```
-| Name | Description |
-| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `examples` | The `Example` objects holding both the predictions and the correct gold-standard annotations. ~~Iterable[Example]~~ |
-| `attr` | The attribute to score. ~~str~~ |
-| _keyword-only_ | |
-| `getter` | Defaults to `getattr`. If provided, `getter(doc, attr)` should return the cats for an individual `Doc`. ~~Callable[[Doc, str], Dict[str, float]]~~ |
-| labels | The set of possible labels. Defaults to `[]`. ~~Iterable[str]~~ |
-| `multi_label` | Whether the attribute allows multiple labels. Defaults to `True`. ~~bool~~ |
-| `positive_label` | The positive label for a binary task with exclusive classes. Defaults to `None`. ~~Optional[str]~~ |
-| **RETURNS** | A dictionary containing the scores, with inapplicable scores as `None`. ~~Dict[str, Optional[float]]~~ |
+| Name | Description |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `examples` | The `Example` objects holding both the predictions and the correct gold-standard annotations. ~~Iterable[Example]~~ |
+| `attr` | The attribute to score. ~~str~~ |
+| _keyword-only_ | |
+| `getter` | Defaults to `getattr`. If provided, `getter(doc, attr)` should return the cats for an individual `Doc`. ~~Callable[[Doc, str], Dict[str, float]]~~ |
+| labels | The set of possible labels. Defaults to `[]`. ~~Iterable[str]~~ |
+| `multi_label` | Whether the attribute allows multiple labels. Defaults to `True`. When set to `False` (exclusive labels), missing gold labels are interpreted as `0.0` and the threshold is set to `0.0`. ~~bool~~ |
+| `positive_label` | The positive label for a binary task with exclusive classes. Defaults to `None`. ~~Optional[str]~~ |
+| `threshold` | Cutoff to consider a prediction "positive". Defaults to `0.5` for multi-label, and `0.0` (i.e. whatever's highest scoring) otherwise. ~~float~~ |
+| **RETURNS** | A dictionary containing the scores, with inapplicable scores as `None`. ~~Dict[str, Optional[float]]~~ |
-## Scorer.score_links {#score_links tag="staticmethod" new="3"}
+## Scorer.score_links {id="score_links",tag="staticmethod",version="3"}
Returns PRF for predicted links on the entity level. To disentangle the
performance of the NEL from the NER, this method only evaluates NEL links for
@@ -263,10 +264,69 @@ entities that overlap between the gold reference and the predictions.
| `negative_labels` | The string values that refer to no annotation (e.g. "NIL"). ~~Iterable[str]~~ |
| **RETURNS** | A dictionary containing the scores. ~~Dict[str, Optional[float]]~~ |
-## get_ner_prf {#get_ner_prf new="3"}
+## get_ner_prf {id="get_ner_prf",version="3"}
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 {id="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 {id="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]]~~ |
diff --git a/website/docs/api/sentencerecognizer.md b/website/docs/api/sentencerecognizer.mdx
similarity index 90%
rename from website/docs/api/sentencerecognizer.md
rename to website/docs/api/sentencerecognizer.mdx
index 29bf10393..5435399f9 100644
--- a/website/docs/api/sentencerecognizer.md
+++ b/website/docs/api/sentencerecognizer.mdx
@@ -2,7 +2,7 @@
title: SentenceRecognizer
tag: class
source: spacy/pipeline/senter.pyx
-new: 3
+version: 3
teaser: 'Pipeline component for sentence segmentation'
api_base_class: /api/tagger
api_string_name: senter
@@ -12,7 +12,7 @@ api_trainable: true
A trainable pipeline component for sentence segmentation. For a simpler,
rule-based strategy, see the [`Sentencizer`](/api/sentencizer).
-## Assigned Attributes {#assigned-attributes}
+## Assigned Attributes {id="assigned-attributes"}
Predicted values will be assigned to `Token.is_sent_start`. The resulting
sentences can be accessed using `Doc.sents`.
@@ -22,7 +22,7 @@ sentences can be accessed using `Doc.sents`.
| `Token.is_sent_start` | A boolean value indicating whether the token starts a sentence. This will be either `True` or `False` for all tokens. ~~bool~~ |
| `Doc.sents` | An iterator over sentences in the `Doc`, determined by `Token.is_sent_start` values. ~~Iterator[Span]~~ |
-## Config and implementation {#config}
+## Config and implementation {id="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
@@ -49,7 +49,7 @@ architectures and their arguments and hyperparameters.
%%GITHUB_SPACY/spacy/pipeline/senter.pyx
```
-## SentenceRecognizer.\_\_init\_\_ {#init tag="method"}
+## SentenceRecognizer.\_\_init\_\_ {id="init",tag="method"}
Initialize the sentence recognizer.
@@ -81,7 +81,7 @@ shortcut for this and instantiate the component using its string name and
| `overwrite` 3.2 | Whether existing annotation is overwritten. Defaults to `False`. ~~bool~~ |
| `scorer` 3.2 | The scoring method. Defaults to [`Scorer.score_spans`](/api/scorer#score_spans) for the attribute `"sents"`. ~~Optional[Callable]~~ |
-## SentenceRecognizer.\_\_call\_\_ {#call tag="method"}
+## SentenceRecognizer.\_\_call\_\_ {id="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
@@ -105,7 +105,7 @@ and all pipeline components are applied to the `Doc` in order. Both
| `doc` | The document to process. ~~Doc~~ |
| **RETURNS** | The processed document. ~~Doc~~ |
-## SentenceRecognizer.pipe {#pipe tag="method"}
+## SentenceRecognizer.pipe {id="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
@@ -129,13 +129,13 @@ and [`pipe`](/api/sentencerecognizer#pipe) delegate to the
| `batch_size` | The number of documents to buffer. Defaults to `128`. ~~int~~ |
| **YIELDS** | The processed documents in order. ~~Doc~~ |
-## SentenceRecognizer.initialize {#initialize tag="method"}
+## SentenceRecognizer.initialize {id="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).
@@ -144,16 +144,16 @@ by [`Language.initialize`](/api/language#initialize).
>
> ```python
> senter = nlp.add_pipe("senter")
-> senter.initialize(lambda: [], nlp=nlp)
+> senter.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]~~ |
-## SentenceRecognizer.predict {#predict tag="method"}
+## SentenceRecognizer.predict {id="predict",tag="method"}
Apply the component's model to a batch of [`Doc`](/api/doc) objects, without
modifying them.
@@ -170,7 +170,7 @@ modifying them.
| `docs` | The documents to predict. ~~Iterable[Doc]~~ |
| **RETURNS** | The model's prediction for each document. |
-## SentenceRecognizer.set_annotations {#set_annotations tag="method"}
+## SentenceRecognizer.set_annotations {id="set_annotations",tag="method"}
Modify a batch of [`Doc`](/api/doc) objects, using pre-computed scores.
@@ -187,7 +187,7 @@ Modify a batch of [`Doc`](/api/doc) objects, using pre-computed scores.
| `docs` | The documents to modify. ~~Iterable[Doc]~~ |
| `scores` | The scores to set, produced by `SentenceRecognizer.predict`. |
-## SentenceRecognizer.update {#update tag="method"}
+## SentenceRecognizer.update {id="update",tag="method"}
Learn from a batch of [`Example`](/api/example) objects containing the
predictions and gold-standard annotations, and update the component's model.
@@ -211,7 +211,7 @@ Delegates to [`predict`](/api/sentencerecognizer#predict) and
| `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]~~ |
-## SentenceRecognizer.rehearse {#rehearse tag="method,experimental" new="3"}
+## SentenceRecognizer.rehearse {id="rehearse",tag="method,experimental",version="3"}
Perform a "rehearsal" update from a batch of data. Rehearsal updates teach the
current model to make predictions similar to an initial model to try to address
@@ -234,7 +234,7 @@ the "catastrophic forgetting" problem. This feature is experimental.
| `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]~~ |
-## SentenceRecognizer.get_loss {#get_loss tag="method"}
+## SentenceRecognizer.get_loss {id="get_loss",tag="method"}
Find the loss and gradient of loss for the batch of documents and their
predicted scores.
@@ -253,7 +253,7 @@ predicted scores.
| `scores` | Scores representing the model's predictions. |
| **RETURNS** | The loss and the gradient, i.e. `(loss, gradient)`. ~~Tuple[float, float]~~ |
-## SentenceRecognizer.create_optimizer {#create_optimizer tag="method"}
+## SentenceRecognizer.create_optimizer {id="create_optimizer",tag="method"}
Create an optimizer for the pipeline component.
@@ -268,7 +268,7 @@ Create an optimizer for the pipeline component.
| ----------- | ---------------------------- |
| **RETURNS** | The optimizer. ~~Optimizer~~ |
-## SentenceRecognizer.use_params {#use_params tag="method, contextmanager"}
+## SentenceRecognizer.use_params {id="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.
@@ -285,7 +285,7 @@ context, the original parameters are restored.
| -------- | -------------------------------------------------- |
| `params` | The parameter values to use in the model. ~~dict~~ |
-## SentenceRecognizer.to_disk {#to_disk tag="method"}
+## SentenceRecognizer.to_disk {id="to_disk",tag="method"}
Serialize the pipe to disk.
@@ -302,7 +302,7 @@ Serialize the pipe to disk.
| _keyword-only_ | |
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
-## SentenceRecognizer.from_disk {#from_disk tag="method"}
+## SentenceRecognizer.from_disk {id="from_disk",tag="method"}
Load the pipe from disk. Modifies the object in place and returns it.
@@ -320,7 +320,7 @@ Load the pipe from disk. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The modified `SentenceRecognizer` object. ~~SentenceRecognizer~~ |
-## SentenceRecognizer.to_bytes {#to_bytes tag="method"}
+## SentenceRecognizer.to_bytes {id="to_bytes",tag="method"}
> #### Example
>
@@ -337,7 +337,7 @@ Serialize the pipe to a bytestring.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The serialized form of the `SentenceRecognizer` object. ~~bytes~~ |
-## SentenceRecognizer.from_bytes {#from_bytes tag="method"}
+## SentenceRecognizer.from_bytes {id="from_bytes",tag="method"}
Load the pipe from a bytestring. Modifies the object in place and returns it.
@@ -356,7 +356,7 @@ Load the pipe from a bytestring. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The `SentenceRecognizer` object. ~~SentenceRecognizer~~ |
-## Serialization fields {#serialization-fields}
+## Serialization fields {id="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
diff --git a/website/docs/api/sentencizer.md b/website/docs/api/sentencizer.mdx
similarity index 94%
rename from website/docs/api/sentencizer.md
rename to website/docs/api/sentencizer.mdx
index b75c7a2f1..9fb5ea71f 100644
--- a/website/docs/api/sentencizer.md
+++ b/website/docs/api/sentencizer.mdx
@@ -13,7 +13,7 @@ performed by the [`DependencyParser`](/api/dependencyparser), so the
`Sentencizer` lets you implement a simpler, rule-based strategy that doesn't
require a statistical model to be loaded.
-## Assigned Attributes {#assigned-attributes}
+## Assigned Attributes {id="assigned-attributes"}
Calculated values will be assigned to `Token.is_sent_start`. The resulting
sentences can be accessed using `Doc.sents`.
@@ -23,7 +23,7 @@ sentences can be accessed using `Doc.sents`.
| `Token.is_sent_start` | A boolean value indicating whether the token starts a sentence. This will be either `True` or `False` for all tokens. ~~bool~~ |
| `Doc.sents` | An iterator over sentences in the `Doc`, determined by `Token.is_sent_start` values. ~~Iterator[Span]~~ |
-## Config and implementation {#config}
+## Config and implementation {id="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
@@ -39,7 +39,7 @@ how the component should be configured. You can override its settings via the
| Setting | Description |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `punct_chars` | Optional custom list of punctuation characters that mark sentence ends. See below for defaults if not set. Defaults to `None`. ~~Optional[List[str]]~~ | `None` |
+| `punct_chars` | Optional custom list of punctuation characters that mark sentence ends. See below for defaults if not set. Defaults to `None`. ~~Optional[List[str]]~~ |
| `overwrite` 3.2 | Whether existing annotation is overwritten. Defaults to `False`. ~~bool~~ |
| `scorer` 3.2 | The scoring method. Defaults to [`Scorer.score_spans`](/api/scorer#score_spans) for the attribute `"sents"` ~~Optional[Callable]~~ |
@@ -47,7 +47,7 @@ how the component should be configured. You can override its settings via the
%%GITHUB_SPACY/spacy/pipeline/sentencizer.pyx
```
-## Sentencizer.\_\_init\_\_ {#init tag="method"}
+## Sentencizer.\_\_init\_\_ {id="init",tag="method"}
Initialize the sentencizer.
@@ -69,8 +69,7 @@ Initialize the sentencizer.
| `overwrite` 3.2 | Whether existing annotation is overwritten. Defaults to `False`. ~~bool~~ |
| `scorer` 3.2 | The scoring method. Defaults to [`Scorer.score_spans`](/api/scorer#score_spans) for the attribute `"sents"` ~~Optional[Callable]~~ |
-```python
-### punct_chars defaults
+```python {title="punct_chars defaults"}
['!', '.', '?', '։', '؟', '۔', '܀', '܁', '܂', '߹', '।', '॥', '၊', '။', '።',
'፧', '፨', '᙮', '᜵', '᜶', '᠃', '᠉', '᥄', '᥅', '᪨', '᪩', '᪪', '᪫',
'᭚', '᭛', '᭞', '᭟', '᰻', '᰼', '᱾', '᱿', '‼', '‽', '⁇', '⁈', '⁉',
@@ -83,7 +82,7 @@ Initialize the sentencizer.
'𑪜', '𑱁', '𑱂', '𖩮', '𖩯', '𖫵', '𖬷', '𖬸', '𖭄', '𛲟', '𝪈', '。', '。']
```
-## Sentencizer.\_\_call\_\_ {#call tag="method"}
+## Sentencizer.\_\_call\_\_ {id="call",tag="method"}
Apply the sentencizer on a `Doc`. Typically, this happens automatically after
the component has been added to the pipeline using
@@ -105,7 +104,7 @@ the component has been added to the pipeline using
| `doc` | The `Doc` object to process, e.g. the `Doc` in the pipeline. ~~Doc~~ |
| **RETURNS** | The modified `Doc` with added sentence boundaries. ~~Doc~~ |
-## Sentencizer.pipe {#pipe tag="method"}
+## Sentencizer.pipe {id="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
@@ -126,7 +125,7 @@ applied to the `Doc` in order.
| `batch_size` | The number of documents to buffer. Defaults to `128`. ~~int~~ |
| **YIELDS** | The processed documents in order. ~~Doc~~ |
-## Sentencizer.to_disk {#to_disk tag="method"}
+## Sentencizer.to_disk {id="to_disk",tag="method"}
Save the sentencizer settings (punctuation characters) to a directory. Will
create a file `sentencizer.json`. This also happens automatically when you save
@@ -144,7 +143,7 @@ an `nlp` object with a sentencizer added to its pipeline.
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `path` | A path to a JSON file, which will be created if it doesn't exist. Paths may be either strings or `Path`-like objects. ~~Union[str, Path]~~ |
-## Sentencizer.from_disk {#from_disk tag="method"}
+## Sentencizer.from_disk {id="from_disk",tag="method"}
Load the sentencizer settings from a file. Expects a JSON file. This also
happens automatically when you load an `nlp` object or model with a sentencizer
@@ -162,7 +161,7 @@ added to its pipeline.
| `path` | A path to a JSON file. Paths may be either strings or `Path`-like objects. ~~Union[str, Path]~~ |
| **RETURNS** | The modified `Sentencizer` object. ~~Sentencizer~~ |
-## Sentencizer.to_bytes {#to_bytes tag="method"}
+## Sentencizer.to_bytes {id="to_bytes",tag="method"}
Serialize the sentencizer settings to a bytestring.
@@ -178,7 +177,7 @@ Serialize the sentencizer settings to a bytestring.
| ----------- | ------------------------------ |
| **RETURNS** | The serialized data. ~~bytes~~ |
-## Sentencizer.from_bytes {#from_bytes tag="method"}
+## Sentencizer.from_bytes {id="from_bytes",tag="method"}
Load the pipe from a bytestring. Modifies the object in place and returns it.
diff --git a/website/docs/api/span-resolver.mdx b/website/docs/api/span-resolver.mdx
new file mode 100644
index 000000000..f061d8df3
--- /dev/null
+++ b/website/docs/api/span-resolver.mdx
@@ -0,0 +1,356 @@
+---
+title: SpanResolver
+tag: class,experimental
+source: spacy-experimental/coref/span_resolver_component.py
+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-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
+[training config](/usage/training#config) or
+`nlp.add_pipe("experimental_span_resolver")` will work out-of-the-box.
+
+
+
+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 {id="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 one. The
+prefixes are configurable.
+
+| Location | Value |
+| ------------------------------------------------- | ------------------------------------------------------------------------- |
+| `Doc.spans[output_prefix + "_" + cluster_number]` | One group of predicted spans. Cluster number starts from 1. ~~SpanGroup~~ |
+
+## Config and implementation {id="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#coref-architectures) documentation for
+details on the architectures and their arguments and hyperparameters.
+
+> #### Example
+>
+> ```python
+> 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,
+> "input_prefix": DEFAULT_CLUSTER_HEAD_PREFIX,
+> "output_prefix": DEFAULT_CLUSTER_PREFIX,
+> },
+> nlp.add_pipe("experimental_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~~ |
+
+## SpanResolver.\_\_init\_\_ {id="init",tag="method"}
+
+> #### Example
+>
+> ```python
+> # Construction via add_pipe with default model
+> 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("experimental_span_resolver", config=config)
+>
+> # Construction from class
+> from spacy_experimental.coref.span_resolver_component 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\_\_ {id="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("experimental_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 {id="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("experimental_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 {id="initialize",tag="method"}
+
+Initialize the component for training. `get_examples` should be a function that
+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).
+
+> #### Example
+>
+> ```python
+> span_resolver = nlp.add_pipe("experimental_span_resolver")
+> 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. Must contain at least one `Example`. ~~Callable[[], Iterable[Example]]~~ |
+| _keyword-only_ | |
+| `nlp` | The current `nlp` object. Defaults to `None`. ~~Optional[Language]~~ |
+
+## SpanResolver.predict {id="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("experimental_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 {id="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("experimental_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 {id="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("experimental_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 {id="create_optimizer",tag="method"}
+
+Create an optimizer for the pipeline component.
+
+> #### Example
+>
+> ```python
+> span_resolver = nlp.add_pipe("experimental_span_resolver")
+> optimizer = span_resolver.create_optimizer()
+> ```
+
+| Name | Description |
+| ----------- | ---------------------------- |
+| **RETURNS** | The optimizer. ~~Optimizer~~ |
+
+## SpanResolver.use_params {id="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("experimental_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 {id="to_disk",tag="method"}
+
+Serialize the pipe to disk.
+
+> #### Example
+>
+> ```python
+> span_resolver = nlp.add_pipe("experimental_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 {id="from_disk",tag="method"}
+
+Load the pipe from disk. Modifies the object in place and returns it.
+
+> #### Example
+>
+> ```python
+> span_resolver = nlp.add_pipe("experimental_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 {id="to_bytes",tag="method"}
+
+> #### Example
+>
+> ```python
+> span_resolver = nlp.add_pipe("experimental_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 {id="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("experimental_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 {id="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. |
diff --git a/website/docs/api/span.md b/website/docs/api/span.mdx
similarity index 75%
rename from website/docs/api/span.md
rename to website/docs/api/span.mdx
index ff7905bc0..bd7794edc 100644
--- a/website/docs/api/span.md
+++ b/website/docs/api/span.mdx
@@ -6,7 +6,7 @@ source: spacy/tokens/span.pyx
A slice from a [`Doc`](/api/doc) object.
-## Span.\_\_init\_\_ {#init tag="method"}
+## Span.\_\_init\_\_ {id="init",tag="method"}
Create a `Span` object from the slice `doc[start : end]`.
@@ -27,8 +27,9 @@ Create a `Span` object from the slice `doc[start : end]`.
| `vector` | A meaning representation of the span. ~~numpy.ndarray[ndim=1, dtype=float32]~~ |
| `vector_norm` | The L2 norm of the document's vector representation. ~~float~~ |
| `kb_id` | A knowledge base ID to attach to the span, e.g. for named entities. ~~Union[str, int]~~ |
+| `span_id` | An ID to associate with the span. ~~Union[str, int]~~ |
-## Span.\_\_getitem\_\_ {#getitem tag="method"}
+## Span.\_\_getitem\_\_ {id="getitem",tag="method"}
Get a `Token` object.
@@ -60,7 +61,7 @@ Get a `Span` object.
| `start_end` | The slice of the span to get. ~~Tuple[int, int]~~ |
| **RETURNS** | The span at `span[start : end]`. ~~Span~~ |
-## Span.\_\_iter\_\_ {#iter tag="method"}
+## Span.\_\_iter\_\_ {id="iter",tag="method"}
Iterate over `Token` objects.
@@ -76,7 +77,7 @@ Iterate over `Token` objects.
| ---------- | --------------------------- |
| **YIELDS** | A `Token` object. ~~Token~~ |
-## Span.\_\_len\_\_ {#len tag="method"}
+## Span.\_\_len\_\_ {id="len",tag="method"}
Get the number of tokens in the span.
@@ -92,7 +93,7 @@ Get the number of tokens in the span.
| ----------- | ----------------------------------------- |
| **RETURNS** | The number of tokens in the span. ~~int~~ |
-## Span.set_extension {#set_extension tag="classmethod" new="2"}
+## Span.set_extension {id="set_extension",tag="classmethod",version="2"}
Define a custom attribute on the `Span` which becomes available via `Span._`.
For details, see the documentation on
@@ -117,7 +118,7 @@ For details, see the documentation on
| `setter` | Setter function that takes the `Span` and a value, and modifies the object. Is called when the user writes to the `Span._` attribute. ~~Optional[Callable[[Span, Any], None]]~~ |
| `force` | Force overwriting existing attribute. ~~bool~~ |
-## Span.get_extension {#get_extension tag="classmethod" new="2"}
+## Span.get_extension {id="get_extension",tag="classmethod",version="2"}
Look up a previously registered extension by name. Returns a 4-tuple
`(default, method, getter, setter)` if the extension is registered. Raises a
@@ -137,7 +138,7 @@ Look up a previously registered extension by name. Returns a 4-tuple
| `name` | Name of the extension. ~~str~~ |
| **RETURNS** | A `(default, method, getter, setter)` tuple of the extension. ~~Tuple[Optional[Any], Optional[Callable], Optional[Callable], Optional[Callable]]~~ |
-## Span.has_extension {#has_extension tag="classmethod" new="2"}
+## Span.has_extension {id="has_extension",tag="classmethod",version="2"}
Check whether an extension has been registered on the `Span` class.
@@ -154,7 +155,7 @@ Check whether an extension has been registered on the `Span` class.
| `name` | Name of the extension to check. ~~str~~ |
| **RETURNS** | Whether the extension has been registered. ~~bool~~ |
-## Span.remove_extension {#remove_extension tag="classmethod" new="2.0.12"}
+## Span.remove_extension {id="remove_extension",tag="classmethod",version="2.0.12"}
Remove a previously registered extension.
@@ -172,7 +173,7 @@ Remove a previously registered extension.
| `name` | Name of the extension. ~~str~~ |
| **RETURNS** | A `(default, method, getter, setter)` tuple of the removed extension. ~~Tuple[Optional[Any], Optional[Callable], Optional[Callable], Optional[Callable]]~~ |
-## Span.char_span {#char_span tag="method" new="2.2.4"}
+## Span.char_span {id="char_span",tag="method",version="2.2.4"}
Create a `Span` object from the slice `span.text[start:end]`. Returns `None` if
the character indices don't map to a valid span.
@@ -185,16 +186,16 @@ the character indices don't map to a valid span.
> assert span.text == "New York"
> ```
-| Name | Description |
-| ------------------------------------ | ----------------------------------------------------------------------------------------- |
-| `start` | The index of the first character of the span. ~~int~~ |
-| `end` | The index of the last character after the span. ~~int~~ |
-| `label` | A label to attach to the span, e.g. for named entities. ~~Union[int, str]~~ |
-| `kb_id` 2.2 | An ID from a knowledge base to capture the meaning of a named entity. ~~Union[int, str]~~ |
-| `vector` | A meaning representation of the span. ~~numpy.ndarray[ndim=1, dtype=float32]~~ |
-| **RETURNS** | The newly constructed object or `None`. ~~Optional[Span]~~ |
+| Name | Description |
+| ----------- | ----------------------------------------------------------------------------------------- |
+| `start` | The index of the first character of the span. ~~int~~ |
+| `end` | The index of the last character after the span. ~~int~~ |
+| `label` | A label to attach to the span, e.g. for named entities. ~~Union[int, str]~~ |
+| `kb_id` | An ID from a knowledge base to capture the meaning of a named entity. ~~Union[int, str]~~ |
+| `vector` | A meaning representation of the span. ~~numpy.ndarray[ndim=1, dtype=float32]~~ |
+| **RETURNS** | The newly constructed object or `None`. ~~Optional[Span]~~ |
-## Span.similarity {#similarity tag="method" model="vectors"}
+## Span.similarity {id="similarity",tag="method",model="vectors"}
Make a semantic similarity estimate. The default estimate is cosine similarity
using an average of word vectors.
@@ -215,7 +216,7 @@ using an average of word vectors.
| `other` | The object to compare with. By default, accepts `Doc`, `Span`, `Token` and `Lexeme` objects. ~~Union[Doc, Span, Token, Lexeme]~~ |
| **RETURNS** | A scalar similarity score. Higher is more similar. ~~float~~ |
-## Span.get_lca_matrix {#get_lca_matrix tag="method"}
+## Span.get_lca_matrix {id="get_lca_matrix",tag="method"}
Calculates the lowest common ancestor matrix for a given `Span`. Returns LCA
matrix containing the integer index of the ancestor, or `-1` if no common
@@ -234,7 +235,7 @@ ancestor is found, e.g. if span excludes a necessary ancestor.
| ----------- | --------------------------------------------------------------------------------------- |
| **RETURNS** | The lowest common ancestor matrix of the `Span`. ~~numpy.ndarray[ndim=2, dtype=int32]~~ |
-## Span.to_array {#to_array tag="method" new="2"}
+## Span.to_array {id="to_array",tag="method",version="2"}
Given a list of `M` attribute IDs, export the tokens to a numpy `ndarray` of
shape `(N, M)`, where `N` is the length of the document. The values will be
@@ -255,7 +256,7 @@ shape `(N, M)`, where `N` is the length of the document. The values will be
| `attr_ids` | A list of attributes (int IDs or string names) or a single attribute (int ID or string name). ~~Union[int, str, List[Union[int, str]]]~~ |
| **RETURNS** | The exported attributes as a numpy array. ~~Union[numpy.ndarray[ndim=2, dtype=uint64], numpy.ndarray[ndim=1, dtype=uint64]]~~ |
-## Span.ents {#ents tag="property" new="2.0.13" model="ner"}
+## Span.ents {id="ents",tag="property",version="2.0.13",model="ner"}
The named entities that fall completely within the span. Returns a tuple of
`Span` objects.
@@ -275,7 +276,7 @@ The named entities that fall completely within the span. Returns a tuple of
| ----------- | ----------------------------------------------------------------- |
| **RETURNS** | Entities in the span, one `Span` per entity. ~~Tuple[Span, ...]~~ |
-## Span.noun_chunks {#noun_chunks tag="property" model="parser"}
+## Span.noun_chunks {id="noun_chunks",tag="property",model="parser"}
Iterate over the base noun phrases in the span. Yields base noun-phrase `Span`
objects, if the document has been syntactically parsed. A base noun phrase, or
@@ -283,8 +284,9 @@ objects, if the document has been syntactically parsed. A base noun phrase, or
it – so no NP-level coordination, no prepositional phrases, and no relative
clauses.
-If the `noun_chunk` [syntax iterator](/usage/adding-languages#language-data) has
-not been implemeted for the given language, a `NotImplementedError` is raised.
+If the `noun_chunk` [syntax iterator](/usage/linguistic-features#language-data)
+has not been implemeted for the given language, a `NotImplementedError` is
+raised.
> #### Example
>
@@ -300,7 +302,7 @@ not been implemeted for the given language, a `NotImplementedError` is raised.
| ---------- | --------------------------------- |
| **YIELDS** | Noun chunks in the span. ~~Span~~ |
-## Span.as_doc {#as_doc tag="method"}
+## Span.as_doc {id="as_doc",tag="method"}
Create a new `Doc` object corresponding to the `Span`, with a copy of the data.
@@ -324,7 +326,7 @@ time.
| `array` | Precomputed array version of the original doc as generated by [`Doc.to_array`](/api/doc#to_array). ~~numpy.ndarray~~ |
| **RETURNS** | A `Doc` object of the `Span`'s content. ~~Doc~~ |
-## Span.root {#root tag="property" model="parser"}
+## Span.root {id="root",tag="property",model="parser"}
The token with the shortest path to the root of the sentence (or the root
itself). If multiple tokens are equally high in the tree, the first token is
@@ -345,7 +347,7 @@ taken.
| ----------- | ------------------------- |
| **RETURNS** | The root token. ~~Token~~ |
-## Span.conjuncts {#conjuncts tag="property" model="parser"}
+## Span.conjuncts {id="conjuncts",tag="property",model="parser"}
A tuple of tokens coordinated to `span.root`.
@@ -361,7 +363,7 @@ A tuple of tokens coordinated to `span.root`.
| ----------- | --------------------------------------------- |
| **RETURNS** | The coordinated tokens. ~~Tuple[Token, ...]~~ |
-## Span.lefts {#lefts tag="property" model="parser"}
+## Span.lefts {id="lefts",tag="property",model="parser"}
Tokens that are to the left of the span, whose heads are within the span.
@@ -377,7 +379,7 @@ Tokens that are to the left of the span, whose heads are within the span.
| ---------- | ---------------------------------------------- |
| **YIELDS** | A left-child of a token of the span. ~~Token~~ |
-## Span.rights {#rights tag="property" model="parser"}
+## Span.rights {id="rights",tag="property",model="parser"}
Tokens that are to the right of the span, whose heads are within the span.
@@ -393,7 +395,7 @@ Tokens that are to the right of the span, whose heads are within the span.
| ---------- | ----------------------------------------------- |
| **YIELDS** | A right-child of a token of the span. ~~Token~~ |
-## Span.n_lefts {#n_lefts tag="property" model="parser"}
+## Span.n_lefts {id="n_lefts",tag="property",model="parser"}
The number of tokens that are to the left of the span, whose heads are within
the span.
@@ -409,7 +411,7 @@ the span.
| ----------- | ---------------------------------------- |
| **RETURNS** | The number of left-child tokens. ~~int~~ |
-## Span.n_rights {#n_rights tag="property" model="parser"}
+## Span.n_rights {id="n_rights",tag="property",model="parser"}
The number of tokens that are to the right of the span, whose heads are within
the span.
@@ -425,7 +427,7 @@ the span.
| ----------- | ----------------------------------------- |
| **RETURNS** | The number of right-child tokens. ~~int~~ |
-## Span.subtree {#subtree tag="property" model="parser"}
+## Span.subtree {id="subtree",tag="property",model="parser"}
Tokens within the span and tokens which descend from them.
@@ -441,7 +443,7 @@ Tokens within the span and tokens which descend from them.
| ---------- | ----------------------------------------------------------- |
| **YIELDS** | A token within the span, or a descendant from it. ~~Token~~ |
-## Span.has_vector {#has_vector tag="property" model="vectors"}
+## Span.has_vector {id="has_vector",tag="property",model="vectors"}
A boolean value indicating whether a word vector is associated with the object.
@@ -456,7 +458,7 @@ A boolean value indicating whether a word vector is associated with the object.
| ----------- | ----------------------------------------------------- |
| **RETURNS** | Whether the span has a vector data attached. ~~bool~~ |
-## Span.vector {#vector tag="property" model="vectors"}
+## Span.vector {id="vector",tag="property",model="vectors"}
A real-valued meaning representation. Defaults to an average of the token
vectors.
@@ -473,7 +475,7 @@ vectors.
| ----------- | ----------------------------------------------------------------------------------------------- |
| **RETURNS** | A 1-dimensional array representing the span's vector. ~~`numpy.ndarray[ndim=1, dtype=float32]~~ |
-## Span.vector_norm {#vector_norm tag="property" model="vectors"}
+## Span.vector_norm {id="vector_norm",tag="property",model="vectors"}
The L2 norm of the span's vector representation.
@@ -490,7 +492,7 @@ The L2 norm of the span's vector representation.
| ----------- | --------------------------------------------------- |
| **RETURNS** | The L2 norm of the vector representation. ~~float~~ |
-## Span.sent {#sent tag="property" model="sentences"}
+## Span.sent {id="sent",tag="property",model="sentences"}
The sentence span that this span is a part of. This property is only available
when [sentence boundaries](/usage/linguistic-features#sbd) have been set on the
@@ -518,14 +520,15 @@ sent = doc[sent.start : max(sent.end, span.end)]
| ----------- | ------------------------------------------------------- |
| **RETURNS** | The sentence span that this span is a part of. ~~Span~~ |
-## Span.sents {#sents tag="property" model="sentences" new="3.2.1"}
+## Span.sents {id="sents",tag="property",model="sentences",version="3.2.1"}
-Returns a generator over the sentences the span belongs to. This property is only available
-when [sentence boundaries](/usage/linguistic-features#sbd) have been set on the
-document by the `parser`, `senter`, `sentencizer` or some custom function. It
-will raise an error otherwise.
+Returns a generator over the sentences the span belongs to. This property is
+only available when [sentence boundaries](/usage/linguistic-features#sbd) have
+been set on the document by the `parser`, `senter`, `sentencizer` or some custom
+function. It will raise an error otherwise.
-If the span happens to cross sentence boundaries, all sentences the span overlaps with will be returned.
+If the span happens to cross sentence boundaries, all sentences the span
+overlaps with will be returned.
> #### Example
>
@@ -539,26 +542,28 @@ If the span happens to cross sentence boundaries, all sentences the span overlap
| ----------- | -------------------------------------------------------------------------- |
| **RETURNS** | A generator yielding sentences this `Span` is a part of ~~Iterable[Span]~~ |
-## Attributes {#attributes}
+## Attributes {id="attributes"}
-| Name | Description |
-| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `doc` | The parent document. ~~Doc~~ |
-| `tensor` 2.1.7 | The span's slice of the parent `Doc`'s tensor. ~~numpy.ndarray~~ |
-| `start` | The token offset for the start of the span. ~~int~~ |
-| `end` | The token offset for the end of the span. ~~int~~ |
-| `start_char` | The character offset for the start of the span. ~~int~~ |
-| `end_char` | The character offset for the end of the span. ~~int~~ |
-| `text` | A string representation of the span text. ~~str~~ |
-| `text_with_ws` | The text content of the span with a trailing whitespace character if the last token has one. ~~str~~ |
-| `orth` | ID of the verbatim text content. ~~int~~ |
-| `orth_` | Verbatim text content (identical to `Span.text`). Exists mostly for consistency with the other attributes. ~~str~~ |
-| `label` | The hash value of the span's label. ~~int~~ |
-| `label_` | The span's label. ~~str~~ |
-| `lemma_` | The span's lemma. Equivalent to `"".join(token.text_with_ws for token in span)`. ~~str~~ |
-| `kb_id` | The hash value of the knowledge base ID referred to by the span. ~~int~~ |
-| `kb_id_` | The knowledge base ID referred to by the span. ~~str~~ |
-| `ent_id` | The hash value of the named entity the token is an instance of. ~~int~~ |
-| `ent_id_` | The string ID of the named entity the token is an instance of. ~~str~~ |
-| `sentiment` | A scalar value indicating the positivity or negativity of the span. ~~float~~ |
-| `_` | User space for adding custom [attribute extensions](/usage/processing-pipelines#custom-components-attributes). ~~Underscore~~ |
+| Name | Description |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `doc` | The parent document. ~~Doc~~ |
+| `tensor` | The span's slice of the parent `Doc`'s tensor. ~~numpy.ndarray~~ |
+| `start` | The token offset for the start of the span. ~~int~~ |
+| `end` | The token offset for the end of the span. ~~int~~ |
+| `start_char` | The character offset for the start of the span. ~~int~~ |
+| `end_char` | The character offset for the end of the span. ~~int~~ |
+| `text` | A string representation of the span text. ~~str~~ |
+| `text_with_ws` | The text content of the span with a trailing whitespace character if the last token has one. ~~str~~ |
+| `orth` | ID of the verbatim text content. ~~int~~ |
+| `orth_` | Verbatim text content (identical to `Span.text`). Exists mostly for consistency with the other attributes. ~~str~~ |
+| `label` | The hash value of the span's label. ~~int~~ |
+| `label_` | The span's label. ~~str~~ |
+| `lemma_` | The span's lemma. Equivalent to `"".join(token.text_with_ws for token in span)`. ~~str~~ |
+| `kb_id` | The hash value of the knowledge base ID referred to by the span. ~~int~~ |
+| `kb_id_` | The knowledge base ID referred to by the span. ~~str~~ |
+| `ent_id` | The hash value of the named entity the root token is an instance of. ~~int~~ |
+| `ent_id_` | The string ID of the named entity the root token is an instance of. ~~str~~ |
+| `id` | The hash value of the span's ID. ~~int~~ |
+| `id_` | The span's ID. ~~str~~ |
+| `sentiment` | A scalar value indicating the positivity or negativity of the span. ~~float~~ |
+| `_` | User space for adding custom [attribute extensions](/usage/processing-pipelines#custom-components-attributes). ~~Underscore~~ |
diff --git a/website/docs/api/spancategorizer.md b/website/docs/api/spancategorizer.mdx
similarity index 89%
rename from website/docs/api/spancategorizer.md
rename to website/docs/api/spancategorizer.mdx
index 26fcaefdf..f39c0aff9 100644
--- a/website/docs/api/spancategorizer.md
+++ b/website/docs/api/spancategorizer.mdx
@@ -2,7 +2,7 @@
title: SpanCategorizer
tag: class,experimental
source: spacy/pipeline/spancat.py
-new: 3.1
+version: 3.1
teaser: 'Pipeline component for labeling potentially overlapping spans of text'
api_base_class: /api/pipe
api_string_name: spancat
@@ -16,7 +16,7 @@ that predicts zero or more labels for each candidate.
Predicted spans will be saved in a [`SpanGroup`](/api/spangroup) on the doc.
Individual span scores can be found in `spangroup.attrs["scores"]`.
-## Assigned Attributes {#assigned-attributes}
+## Assigned Attributes {id="assigned-attributes"}
Predictions will be saved to `Doc.spans[spans_key]` as a
[`SpanGroup`](/api/spangroup). The scores for the spans in the `SpanGroup` will
@@ -29,7 +29,7 @@ be saved in `SpanGroup.attrs["scores"]`.
| `Doc.spans[spans_key]` | The annotated spans. ~~SpanGroup~~ |
| `Doc.spans[spans_key].attrs["scores"]` | The score for each span in the `SpanGroup`. ~~Floats1d~~ |
-## Config and implementation {#config}
+## Config and implementation {id="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
@@ -56,7 +56,7 @@ architectures and their arguments and hyperparameters.
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `suggester` | A function that [suggests spans](#suggesters). Spans are returned as a ragged array with two integer columns, for the start and end positions. Defaults to [`ngram_suggester`](#ngram_suggester). ~~Callable[[Iterable[Doc], Optional[Ops]], Ragged]~~ |
| `model` | A model instance that is given a a list of documents and `(start, end)` indices representing candidate span offsets. The model predicts a probability for each category for each span. Defaults to [SpanCategorizer](/api/architectures#SpanCategorizer). ~~Model[Tuple[List[Doc], Ragged], Floats2d]~~ |
-| `spans_key` | Key of the [`Doc.spans`](/api/doc#spans) dict to save the spans under. During initialization and training, the component will look for spans on the reference document under the same key. Defaults to `"spans"`. ~~str~~ |
+| `spans_key` | Key of the [`Doc.spans`](/api/doc#spans) dict to save the spans under. During initialization and training, the component will look for spans on the reference document under the same key. Defaults to `"sc"`. ~~str~~ |
| `threshold` | Minimum probability to consider a prediction positive. Spans with a positive prediction will be saved on the Doc. Defaults to `0.5`. ~~float~~ |
| `max_positive` | Maximum number of labels to consider positive per span. Defaults to `None`, indicating no limit. ~~Optional[int]~~ |
| `scorer` | The scoring method. Defaults to [`Scorer.score_spans`](/api/scorer#score_spans) for `Doc.spans[spans_key]` with overlapping spans allowed. ~~Optional[Callable]~~ |
@@ -65,7 +65,7 @@ architectures and their arguments and hyperparameters.
%%GITHUB_SPACY/spacy/pipeline/spancat.py
```
-## SpanCategorizer.\_\_init\_\_ {#init tag="method"}
+## SpanCategorizer.\_\_init\_\_ {id="init",tag="method"}
> #### Example
>
@@ -93,11 +93,11 @@ shortcut for this and instantiate the component using its string name and
| `suggester` | A function that [suggests spans](#suggesters). Spans are returned as a ragged array with two integer columns, for the start and end positions. ~~Callable[[Iterable[Doc], Optional[Ops]], Ragged]~~ |
| `name` | String name of the component instance. Used to add entries to the `losses` during training. ~~str~~ |
| _keyword-only_ | |
-| `spans_key` | Key of the [`Doc.spans`](/api/doc#sans) dict to save the spans under. During initialization and training, the component will look for spans on the reference document under the same key. Defaults to `"spans"`. ~~str~~ |
+| `spans_key` | Key of the [`Doc.spans`](/api/doc#sans) dict to save the spans under. During initialization and training, the component will look for spans on the reference document under the same key. Defaults to `"sc"`. ~~str~~ |
| `threshold` | Minimum probability to consider a prediction positive. Spans with a positive prediction will be saved on the Doc. Defaults to `0.5`. ~~float~~ |
| `max_positive` | Maximum number of labels to consider positive per span. Defaults to `None`, indicating no limit. ~~Optional[int]~~ |
-## SpanCategorizer.\_\_call\_\_ {#call tag="method"}
+## SpanCategorizer.\_\_call\_\_ {id="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
@@ -120,7 +120,7 @@ delegate to the [`predict`](/api/spancategorizer#predict) and
| `doc` | The document to process. ~~Doc~~ |
| **RETURNS** | The processed document. ~~Doc~~ |
-## SpanCategorizer.pipe {#pipe tag="method"}
+## SpanCategorizer.pipe {id="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
@@ -144,13 +144,13 @@ applied to the `Doc` in order. Both [`__call__`](/api/spancategorizer#call) and
| `batch_size` | The number of documents to buffer. Defaults to `128`. ~~int~~ |
| **YIELDS** | The processed documents in order. ~~Doc~~ |
-## SpanCategorizer.initialize {#initialize tag="method"}
+## SpanCategorizer.initialize {id="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) and lets you customize
@@ -162,7 +162,7 @@ config.
>
> ```python
> spancat = nlp.add_pipe("spancat")
-> spancat.initialize(lambda: [], nlp=nlp)
+> spancat.initialize(lambda: examples, nlp=nlp)
> ```
>
> ```ini
@@ -176,12 +176,12 @@ config.
| Name | Description |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `get_examples` | Function that returns gold-standard annotations in the form of [`Example`](/api/example) objects. ~~Callable[[], Iterable[Example]]~~ |
+| `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]~~ |
| `labels` | The label information to add to the component, as provided by the [`label_data`](#label_data) property after initialization. To generate a reusable JSON file from your data, you should run the [`init labels`](/api/cli#init-labels) command. If no labels are provided, the `get_examples` callback is used to extract the labels from the data, which may be a lot slower. ~~Optional[Iterable[str]]~~ |
-## SpanCategorizer.predict {#predict tag="method"}
+## SpanCategorizer.predict {id="predict",tag="method"}
Apply the component's model to a batch of [`Doc`](/api/doc) objects without
modifying them.
@@ -198,7 +198,7 @@ modifying them.
| `docs` | The documents to predict. ~~Iterable[Doc]~~ |
| **RETURNS** | The model's prediction for each document. |
-## SpanCategorizer.set_annotations {#set_annotations tag="method"}
+## SpanCategorizer.set_annotations {id="set_annotations",tag="method"}
Modify a batch of [`Doc`](/api/doc) objects using pre-computed scores.
@@ -215,7 +215,7 @@ Modify a batch of [`Doc`](/api/doc) objects using pre-computed scores.
| `docs` | The documents to modify. ~~Iterable[Doc]~~ |
| `scores` | The scores to set, produced by `SpanCategorizer.predict`. |
-## SpanCategorizer.update {#update tag="method"}
+## SpanCategorizer.update {id="update",tag="method"}
Learn from a batch of [`Example`](/api/example) objects containing the
predictions and gold-standard annotations, and update the component's model.
@@ -239,7 +239,25 @@ Delegates to [`predict`](/api/spancategorizer#predict) and
| `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]~~ |
-## SpanCategorizer.get_loss {#get_loss tag="method"}
+## SpanCategorizer.set_candidates {id="set_candidates",tag="method", version="3.3"}
+
+Use the suggester to add a list of [`Span`](/api/span) candidates to a list of
+[`Doc`](/api/doc) objects. This method is intended to be used for debugging
+purposes.
+
+> #### Example
+>
+> ```python
+> spancat = nlp.add_pipe("spancat")
+> spancat.set_candidates(docs, "candidates")
+> ```
+
+| Name | Description |
+| ---------------- | -------------------------------------------------------------------- |
+| `docs` | The documents to modify. ~~Iterable[Doc]~~ |
+| `candidates_key` | Key of the Doc.spans dict to save the candidate spans under. ~~str~~ |
+
+## SpanCategorizer.get_loss {id="get_loss",tag="method"}
Find the loss and gradient of loss for the batch of documents and their
predicted scores.
@@ -258,7 +276,7 @@ predicted scores.
| `spans_scores` | Scores representing the model's predictions. ~~Tuple[Ragged, Floats2d]~~ |
| **RETURNS** | The loss and the gradient, i.e. `(loss, gradient)`. ~~Tuple[float, float]~~ |
-## SpanCategorizer.create_optimizer {#create_optimizer tag="method"}
+## SpanCategorizer.create_optimizer {id="create_optimizer",tag="method"}
Create an optimizer for the pipeline component.
@@ -273,7 +291,7 @@ Create an optimizer for the pipeline component.
| ----------- | ---------------------------- |
| **RETURNS** | The optimizer. ~~Optimizer~~ |
-## SpanCategorizer.use_params {#use_params tag="method, contextmanager"}
+## SpanCategorizer.use_params {id="use_params",tag="method, contextmanager"}
Modify the pipe's model to use the given parameter values.
@@ -289,7 +307,7 @@ Modify the pipe's model to use the given parameter values.
| -------- | -------------------------------------------------- |
| `params` | The parameter values to use in the model. ~~dict~~ |
-## SpanCategorizer.add_label {#add_label tag="method"}
+## SpanCategorizer.add_label {id="add_label",tag="method"}
Add a new label to the pipe. Raises an error if the output dimension is already
set, or if the model has already been fully [initialized](#initialize). Note
@@ -311,7 +329,7 @@ automatically.
| `label` | The label to add. ~~str~~ |
| **RETURNS** | `0` if the label is already present, otherwise `1`. ~~int~~ |
-## SpanCategorizer.to_disk {#to_disk tag="method"}
+## SpanCategorizer.to_disk {id="to_disk",tag="method"}
Serialize the pipe to disk.
@@ -328,7 +346,7 @@ Serialize the pipe to disk.
| _keyword-only_ | |
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
-## SpanCategorizer.from_disk {#from_disk tag="method"}
+## SpanCategorizer.from_disk {id="from_disk",tag="method"}
Load the pipe from disk. Modifies the object in place and returns it.
@@ -346,7 +364,7 @@ Load the pipe from disk. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The modified `SpanCategorizer` object. ~~SpanCategorizer~~ |
-## SpanCategorizer.to_bytes {#to_bytes tag="method"}
+## SpanCategorizer.to_bytes {id="to_bytes",tag="method"}
> #### Example
>
@@ -363,7 +381,7 @@ Serialize the pipe to a bytestring.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The serialized form of the `SpanCategorizer` object. ~~bytes~~ |
-## SpanCategorizer.from_bytes {#from_bytes tag="method"}
+## SpanCategorizer.from_bytes {id="from_bytes",tag="method"}
Load the pipe from a bytestring. Modifies the object in place and returns it.
@@ -382,7 +400,7 @@ Load the pipe from a bytestring. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The `SpanCategorizer` object. ~~SpanCategorizer~~ |
-## SpanCategorizer.labels {#labels tag="property"}
+## SpanCategorizer.labels {id="labels",tag="property"}
The labels currently added to the component.
@@ -397,7 +415,7 @@ The labels currently added to the component.
| ----------- | ------------------------------------------------------ |
| **RETURNS** | The labels added to the component. ~~Tuple[str, ...]~~ |
-## SpanCategorizer.label_data {#label_data tag="property"}
+## SpanCategorizer.label_data {id="label_data",tag="property"}
The labels currently added to the component and their internal meta information.
This is the data generated by [`init labels`](/api/cli#init-labels) and used by
@@ -415,7 +433,7 @@ the model with a pre-defined label set.
| ----------- | ---------------------------------------------------------- |
| **RETURNS** | The label data added to the component. ~~Tuple[str, ...]~~ |
-## Serialization fields {#serialization-fields}
+## Serialization fields {id="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
@@ -433,9 +451,9 @@ serialization by passing in the string names via the `exclude` argument.
| `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. |
-## Suggesters {#suggesters tag="registered functions" source="spacy/pipeline/spancat.py"}
+## Suggesters {id="suggesters",tag="registered functions",source="spacy/pipeline/spancat.py"}
-### spacy.ngram_suggester.v1 {#ngram_suggester}
+### spacy.ngram_suggester.v1 {id="ngram_suggester"}
> #### Example Config
>
@@ -453,7 +471,7 @@ integers. The array has two columns, indicating the start and end position.
| `sizes` | The phrase lengths to suggest. For example, `[1, 2]` will suggest phrases consisting of 1 or 2 tokens. ~~List[int]~~ |
| **CREATES** | The suggester function. ~~Callable[[Iterable[Doc], Optional[Ops]], Ragged]~~ |
-### spacy.ngram_range_suggester.v1 {#ngram_range_suggester}
+### spacy.ngram_range_suggester.v1 {id="ngram_range_suggester"}
> #### Example Config
>
diff --git a/website/docs/api/spangroup.md b/website/docs/api/spangroup.md
deleted file mode 100644
index 654067eb1..000000000
--- a/website/docs/api/spangroup.md
+++ /dev/null
@@ -1,195 +0,0 @@
----
-title: SpanGroup
-tag: class
-source: spacy/tokens/span_group.pyx
-new: 3
----
-
-A group of arbitrary, potentially overlapping [`Span`](/api/span) objects that
-all belong to the same [`Doc`](/api/doc) object. The group can be named, and you
-can attach additional attributes to it. Span groups are generally accessed via
-the [`Doc.spans`](/api/doc#spans) attribute, which will convert lists of spans
-into a `SpanGroup` object for you automatically on assignment. `SpanGroup`
-objects behave similar to `list`s, so you can append `Span` objects to them or
-access a member at a given index.
-
-## SpanGroup.\_\_init\_\_ {#init tag="method"}
-
-Create a `SpanGroup`.
-
-> #### Example
->
-> ```python
-> doc = nlp("Their goi ng home")
-> spans = [doc[0:1], doc[2:4]]
->
-> # 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 {#doc tag="property"}
-
-The [`Doc`](/api/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
->
-> ```python
-> doc = nlp("Their goi ng home")
-> doc.spans["errors"] = [doc[0:1], doc[2:4]]
-> assert doc.spans["errors"].doc == doc
-> ```
-
-| Name | Description |
-| ----------- | ------------------------------- |
-| **RETURNS** | The reference document. ~~Doc~~ |
-
-## SpanGroup.has_overlap {#has_overlap tag="property"}
-
-Check whether the span group contains overlapping spans.
-
-> #### Example
->
-> ```python
-> doc = nlp("Their goi ng home")
-> doc.spans["errors"] = [doc[0:1], doc[2:4]]
-> assert not doc.spans["errors"].has_overlap
-> doc.spans["errors"].append(doc[1:2])
-> assert doc.spans["errors"].has_overlap
-> ```
-
-| Name | Description |
-| ----------- | -------------------------------------------------- |
-| **RETURNS** | Whether the span group contains overlaps. ~~bool~~ |
-
-## SpanGroup.\_\_len\_\_ {#len tag="method"}
-
-Get the number of spans in the group.
-
-> #### Example
->
-> ```python
-> doc = nlp("Their goi ng home")
-> doc.spans["errors"] = [doc[0:1], doc[2:4]]
-> assert len(doc.spans["errors"]) == 2
-> ```
-
-| Name | Description |
-| ----------- | ----------------------------------------- |
-| **RETURNS** | The number of spans in the group. ~~int~~ |
-
-## SpanGroup.\_\_getitem\_\_ {#getitem tag="method"}
-
-Get a span from the group.
-
-> #### Example
->
-> ```python
-> doc = nlp("Their goi ng home")
-> doc.spans["errors"] = [doc[0:1], doc[2:4]]
-> span = doc.spans["errors"][1]
-> assert span.text == "goi ng"
-> ```
-
-| Name | Description |
-| ----------- | ------------------------------------- |
-| `i` | The item index. ~~int~~ |
-| **RETURNS** | The span at the given index. ~~Span~~ |
-
-## SpanGroup.append {#append tag="method"}
-
-Add a [`Span`](/api/span) object to the group. The span must refer to the same
-[`Doc`](/api/doc) object as the span group.
-
-> #### Example
->
-> ```python
-> doc = nlp("Their goi ng home")
-> doc.spans["errors"] = [doc[0:1]]
-> doc.spans["errors"].append(doc[2:4])
-> assert len(doc.spans["errors"]) == 2
-> ```
-
-| Name | Description |
-| ------ | ---------------------------- |
-| `span` | The span to append. ~~Span~~ |
-
-## SpanGroup.extend {#extend tag="method"}
-
-Add multiple [`Span`](/api/span) objects to the group. All spans must refer to
-the same [`Doc`](/api/doc) object as the span group.
-
-> #### Example
->
-> ```python
-> doc = nlp("Their goi ng home")
-> doc.spans["errors"] = []
-> doc.spans["errors"].extend([doc[2:4], doc[0:1]])
-> assert len(doc.spans["errors"]) == 2
-> ```
-
-| Name | Description |
-| ------- | ------------------------------------ |
-| `spans` | The spans to add. ~~Iterable[Span]~~ |
-
-## SpanGroup.to_bytes {#to_bytes tag="method"}
-
-Serialize the span group to a bytestring.
-
-> #### Example
->
-> ```python
-> doc = nlp("Their goi ng home")
-> doc.spans["errors"] = [doc[0:1], doc[2:4]]
-> group_bytes = doc.spans["errors"].to_bytes()
-> ```
-
-| Name | Description |
-| ----------- | ------------------------------------- |
-| **RETURNS** | The serialized `SpanGroup`. ~~bytes~~ |
-
-## SpanGroup.from_bytes {#from_bytes tag="method"}
-
-Load the span group from a bytestring. Modifies the object in place and returns
-it.
-
-> #### Example
->
-> ```python
-> from spacy.tokens import SpanGroup
->
-> doc = nlp("Their goi ng home")
-> doc.spans["errors"] = [doc[0:1], doc[2:4]]
-> 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~~ |
diff --git a/website/docs/api/spangroup.mdx b/website/docs/api/spangroup.mdx
new file mode 100644
index 000000000..cd0accb6a
--- /dev/null
+++ b/website/docs/api/spangroup.mdx
@@ -0,0 +1,317 @@
+---
+title: SpanGroup
+tag: class
+source: spacy/tokens/span_group.pyx
+version: 3
+---
+
+A group of arbitrary, potentially overlapping [`Span`](/api/span) objects that
+all belong to the same [`Doc`](/api/doc) object. The group can be named, and you
+can attach additional attributes to it. Span groups are generally accessed via
+the [`Doc.spans`](/api/doc#spans) attribute, which will convert lists of spans
+into a `SpanGroup` object for you automatically on assignment. `SpanGroup`
+objects behave similar to `list`s, so you can append `Span` objects to them or
+access a member at a given index.
+
+## SpanGroup.\_\_init\_\_ {id="init",tag="method"}
+
+Create a `SpanGroup`.
+
+> #### Example
+>
+> ```python
+> 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 {id="doc",tag="property"}
+
+The [`Doc`](/api/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
+>
+> ```python
+> 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 {id="has_overlap",tag="property"}
+
+Check whether the span group contains overlapping spans.
+
+> #### Example
+>
+> ```python
+> 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\_\_ {id="len",tag="method"}
+
+Get the number of spans in the group.
+
+> #### Example
+>
+> ```python
+> 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\_\_ {id="getitem",tag="method"}
+
+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
+>
+> ```python
+> 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\_\_ {id="setitem",tag="method", version="3.3"}
+
+Set a span in the span group.
+
+> #### Example
+>
+> ```python
+> 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\_\_ {id="delitem",tag="method", version="3.3"}
+
+Delete a span from the span group.
+
+> #### Example
+>
+> ```python
+> 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\_\_ {id="add",tag="method", version="3.3"}
+
+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
+>
+> ```python
+> 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\_\_ {id="iadd",tag="method", version="3.3"}
+
+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
+>
+> ```python
+> 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.\_\_iter\_\_ {id="iter",tag="method",version="3.5"}
+
+Iterate over the spans in this span group.
+
+> #### Example
+>
+> ```python
+> doc = nlp("Their goi ng home")
+> doc.spans["errors"] = [doc[0:1], doc[1:3]]
+> for error_span in doc.spans["errors"]:
+> print(error_span)
+> ```
+
+| Name | Description |
+| ---------- | ----------------------------------- |
+| **YIELDS** | A span in this span group. ~~Span~~ |
+
+
+## SpanGroup.append {id="append",tag="method"}
+
+Add a [`Span`](/api/span) object to the group. The span must refer to the same
+[`Doc`](/api/doc) object as the span group.
+
+> #### Example
+>
+> ```python
+> 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 {id="extend",tag="method"}
+
+Add multiple [`Span`](/api/span) objects or contents of another `SpanGroup` to
+the group. All spans must refer to the same [`Doc`](/api/doc) object as the span
+group.
+
+> #### Example
+>
+> ```python
+> 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 {id="copy",tag="method", version="3.3"}
+
+Return a copy of the span group.
+
+> #### Example
+>
+> ```python
+> 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 |
+| ----------- | -------------------------------------------------------------------------------------------------- |
+| `doc` | The document to which the copy is bound. Defaults to `None` for the current doc. ~~Optional[Doc]~~ |
+| **RETURNS** | A copy of the `SpanGroup` object. ~~SpanGroup~~ |
+
+## SpanGroup.to_bytes {id="to_bytes",tag="method"}
+
+Serialize the span group to a bytestring.
+
+> #### Example
+>
+> ```python
+> 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 {id="from_bytes",tag="method"}
+
+Load the span group from a bytestring. Modifies the object in place and returns
+it.
+
+> #### Example
+>
+> ```python
+> 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~~ |
diff --git a/website/docs/api/spanruler.mdx b/website/docs/api/spanruler.mdx
new file mode 100644
index 000000000..d2d41f620
--- /dev/null
+++ b/website/docs/api/spanruler.mdx
@@ -0,0 +1,353 @@
+---
+title: SpanRuler
+tag: class
+source: spacy/pipeline/span_ruler.py
+version: 3.3
+teaser: 'Pipeline component for rule-based span and named entity recognition'
+api_string_name: span_ruler
+api_trainable: false
+---
+
+The span ruler lets you add spans to [`Doc.spans`](/api/doc#spans) and/or
+[`Doc.ents`](/api/doc#ents) using token-based rules or exact phrase matches. For
+usage examples, see the docs on
+[rule-based span matching](/usage/rule-based-matching#spanruler).
+
+## Assigned Attributes {id="assigned-attributes"}
+
+Matches will be saved to `Doc.spans[spans_key]` as a
+[`SpanGroup`](/api/spangroup) and/or to `Doc.ents`, where the annotation is
+saved in the `Token.ent_type` and `Token.ent_iob` fields.
+
+| Location | Value |
+| ---------------------- | ----------------------------------------------------------------- |
+| `Doc.spans[spans_key]` | The annotated spans. ~~SpanGroup~~ |
+| `Doc.ents` | The annotated spans. ~~Tuple[Span]~~ |
+| `Token.ent_iob` | An enum encoding of the IOB part of the named entity tag. ~~int~~ |
+| `Token.ent_iob_` | The IOB part of the named entity tag. ~~str~~ |
+| `Token.ent_type` | The label part of the named entity tag (hash). ~~int~~ |
+| `Token.ent_type_` | The label part of the named entity tag. ~~str~~ |
+
+## Config and implementation {id="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`](/usage/training#config).
+
+> #### Example
+>
+> ```python
+> config = {
+> "spans_key": "my_spans",
+> "validate": True,
+> "overwrite": False,
+> }
+> nlp.add_pipe("span_ruler", config=config)
+> ```
+
+| Setting | Description |
+| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `spans_key` | The spans key to save the spans under. If `None`, no spans are saved. Defaults to `"ruler"`. ~~Optional[str]~~ |
+| `spans_filter` | The optional method to filter spans before they are assigned to doc.spans. Defaults to `None`. ~~Optional[Callable[[Iterable[Span], Iterable[Span]], List[Span]]]~~ |
+| `annotate_ents` | Whether to save spans to doc.ents. Defaults to `False`. ~~bool~~ |
+| `ents_filter` | The method to filter spans before they are assigned to doc.ents. Defaults to `util.filter_chain_spans`. ~~Callable[[Iterable[Span], Iterable[Span]], List[Span]]~~ |
+| `phrase_matcher_attr` | Token attribute to match on, passed to the internal `PhraseMatcher` as `attr`. Defaults to `None`. ~~Optional[Union[int, str]]~~ |
+| `matcher_fuzzy_compare` 3.5 | The fuzzy comparison method, passed on to the internal `Matcher`. Defaults to `spacy.matcher.levenshtein.levenshtein_compare`. ~~Callable~~ |
+| `validate` | Whether patterns should be validated, passed to `Matcher` and `PhraseMatcher` as `validate`. Defaults to `False`. ~~bool~~ |
+| `overwrite` | Whether to remove any existing spans under `Doc.spans[spans key]` if `spans_key` is set, or to remove any ents under `Doc.ents` if `annotate_ents` is set. Defaults to `True`. ~~bool~~ |
+| `scorer` | The scoring method. Defaults to [`Scorer.score_spans`](/api/scorer#score_spans) for `Doc.spans[spans_key]` with overlapping spans allowed. ~~Optional[Callable]~~ |
+
+```python
+%%GITHUB_SPACY/spacy/pipeline/span_ruler.py
+```
+
+## SpanRuler.\_\_init\_\_ {id="init",tag="method"}
+
+Initialize the span ruler. If patterns are supplied here, they need to be a list
+of dictionaries with a `"label"` and `"pattern"` key. A pattern can either be a
+token pattern (list) or a phrase pattern (string). For example:
+`{"label": "ORG", "pattern": "Apple"}`.
+
+> #### Example
+>
+> ```python
+> # Construction via add_pipe
+> ruler = nlp.add_pipe("span_ruler")
+>
+> # Construction from class
+> from spacy.pipeline import SpanRuler
+> ruler = SpanRuler(nlp, overwrite=True)
+> ```
+
+| Name | Description |
+| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `nlp` | The shared nlp object to pass the vocab to the matchers and process phrase patterns. ~~Language~~ |
+| `name` | Instance name of the current pipeline component. Typically passed in automatically from the factory when the component is added. Used to disable the current span ruler while creating phrase patterns with the nlp object. ~~str~~ |
+| _keyword-only_ | |
+| `spans_key` | The spans key to save the spans under. If `None`, no spans are saved. Defaults to `"ruler"`. ~~Optional[str]~~ |
+| `spans_filter` | The optional method to filter spans before they are assigned to doc.spans. Defaults to `None`. ~~Optional[Callable[[Iterable[Span], Iterable[Span]], List[Span]]]~~ |
+| `annotate_ents` | Whether to save spans to doc.ents. Defaults to `False`. ~~bool~~ |
+| `ents_filter` | The method to filter spans before they are assigned to doc.ents. Defaults to `util.filter_chain_spans`. ~~Callable[[Iterable[Span], Iterable[Span]], List[Span]]~~ |
+| `phrase_matcher_attr` | Token attribute to match on, passed to the internal PhraseMatcher as `attr`. Defaults to `None`. ~~Optional[Union[int, str]]~~ |
+| `matcher_fuzzy_compare` 3.5 | The fuzzy comparison method, passed on to the internal `Matcher`. Defaults to `spacy.matcher.levenshtein.levenshtein_compare`. ~~Callable~~ |
+| `validate` | Whether patterns should be validated, passed to Matcher and PhraseMatcher as `validate`. Defaults to `False`. ~~bool~~ |
+| `overwrite` | Whether to remove any existing spans under `Doc.spans[spans key]` if `spans_key` is set, or to remove any ents under `Doc.ents` if `annotate_ents` is set. Defaults to `True`. ~~bool~~ |
+| `scorer` | The scoring method. Defaults to [`Scorer.score_spans`](/api/scorer#score_spans) for `Doc.spans[spans_key]` with overlapping spans allowed. ~~Optional[Callable]~~ |
+
+## SpanRuler.initialize {id="initialize",tag="method"}
+
+Initialize the component with data and used before training to load in rules
+from a [pattern file](/usage/rule-based-matching/#spanruler-files). This method
+is typically called by [`Language.initialize`](/api/language#initialize) and
+lets you customize arguments it receives via the
+[`[initialize.components]`](/api/data-formats#config-initialize) block in the
+config. Any existing patterns are removed on initialization.
+
+> #### Example
+>
+> ```python
+> span_ruler = nlp.add_pipe("span_ruler")
+> span_ruler.initialize(lambda: [], nlp=nlp, patterns=patterns)
+> ```
+>
+> ```ini
+> ### config.cfg
+> [initialize.components.span_ruler]
+>
+> [initialize.components.span_ruler.patterns]
+> @readers = "srsly.read_jsonl.v1"
+> path = "corpus/span_ruler_patterns.jsonl
+> ```
+
+| Name | Description |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `get_examples` | Function that returns gold-standard annotations in the form of [`Example`](/api/example) objects. Not used by the `SpanRuler`. ~~Callable[[], Iterable[Example]]~~ |
+| _keyword-only_ | |
+| `nlp` | The current `nlp` object. Defaults to `None`. ~~Optional[Language]~~ |
+| `patterns` | The list of patterns. Defaults to `None`. ~~Optional[Sequence[Dict[str, Union[str, List[Dict[str, Any]]]]]]~~ |
+
+## SpanRuler.\_\_len\_\_ {id="len",tag="method"}
+
+The number of all patterns added to the span ruler.
+
+> #### Example
+>
+> ```python
+> ruler = nlp.add_pipe("span_ruler")
+> assert len(ruler) == 0
+> ruler.add_patterns([{"label": "ORG", "pattern": "Apple"}])
+> assert len(ruler) == 1
+> ```
+
+| Name | Description |
+| ----------- | ------------------------------- |
+| **RETURNS** | The number of patterns. ~~int~~ |
+
+## SpanRuler.\_\_contains\_\_ {id="contains",tag="method"}
+
+Whether a label is present in the patterns.
+
+> #### Example
+>
+> ```python
+> ruler = nlp.add_pipe("span_ruler")
+> ruler.add_patterns([{"label": "ORG", "pattern": "Apple"}])
+> assert "ORG" in ruler
+> assert not "PERSON" in ruler
+> ```
+
+| Name | Description |
+| ----------- | --------------------------------------------------- |
+| `label` | The label to check. ~~str~~ |
+| **RETURNS** | Whether the span ruler contains the label. ~~bool~~ |
+
+## SpanRuler.\_\_call\_\_ {id="call",tag="method"}
+
+Find matches in the `Doc` and add them to `doc.spans[span_key]` and/or
+`doc.ents`. Typically, this happens automatically after the component has been
+added to the pipeline using [`nlp.add_pipe`](/api/language#add_pipe). If the
+span ruler was initialized with `overwrite=True`, existing spans and entities
+will be removed.
+
+> #### Example
+>
+> ```python
+> ruler = nlp.add_pipe("span_ruler")
+> ruler.add_patterns([{"label": "ORG", "pattern": "Apple"}])
+>
+> doc = nlp("A text about Apple.")
+> spans = [(span.text, span.label_) for span in doc.spans["ruler"]]
+> assert spans == [("Apple", "ORG")]
+> ```
+
+| Name | Description |
+| ----------- | -------------------------------------------------------------------- |
+| `doc` | The `Doc` object to process, e.g. the `Doc` in the pipeline. ~~Doc~~ |
+| **RETURNS** | The modified `Doc` with added spans/entities. ~~Doc~~ |
+
+## SpanRuler.add_patterns {id="add_patterns",tag="method"}
+
+Add patterns to the span ruler. A pattern can either be a token pattern (list of
+dicts) or a phrase pattern (string). For more details, see the usage guide on
+[rule-based matching](/usage/rule-based-matching).
+
+> #### Example
+>
+> ```python
+> patterns = [
+> {"label": "ORG", "pattern": "Apple"},
+> {"label": "GPE", "pattern": [{"lower": "san"}, {"lower": "francisco"}]}
+> ]
+> ruler = nlp.add_pipe("span_ruler")
+> ruler.add_patterns(patterns)
+> ```
+
+| Name | Description |
+| ---------- | ---------------------------------------------------------------- |
+| `patterns` | The patterns to add. ~~List[Dict[str, Union[str, List[dict]]]]~~ |
+
+## SpanRuler.remove {id="remove",tag="method"}
+
+Remove patterns by label from the span ruler. A `ValueError` is raised if the
+label does not exist in any patterns.
+
+> #### Example
+>
+> ```python
+> patterns = [{"label": "ORG", "pattern": "Apple", "id": "apple"}]
+> ruler = nlp.add_pipe("span_ruler")
+> ruler.add_patterns(patterns)
+> ruler.remove("ORG")
+> ```
+
+| Name | Description |
+| ------- | -------------------------------------- |
+| `label` | The label of the pattern rule. ~~str~~ |
+
+## SpanRuler.remove_by_id {id="remove_by_id",tag="method"}
+
+Remove patterns by ID from the span ruler. A `ValueError` is raised if the ID
+does not exist in any patterns.
+
+> #### Example
+>
+> ```python
+> patterns = [{"label": "ORG", "pattern": "Apple", "id": "apple"}]
+> ruler = nlp.add_pipe("span_ruler")
+> ruler.add_patterns(patterns)
+> ruler.remove_by_id("apple")
+> ```
+
+| Name | Description |
+| ------------ | ----------------------------------- |
+| `pattern_id` | The ID of the pattern rule. ~~str~~ |
+
+## SpanRuler.clear {id="clear",tag="method"}
+
+Remove all patterns the span ruler.
+
+> #### Example
+>
+> ```python
+> patterns = [{"label": "ORG", "pattern": "Apple", "id": "apple"}]
+> ruler = nlp.add_pipe("span_ruler")
+> ruler.add_patterns(patterns)
+> ruler.clear()
+> ```
+
+## SpanRuler.to_disk {id="to_disk",tag="method"}
+
+Save the span ruler patterns to a directory. The patterns will be saved as
+newline-delimited JSON (JSONL).
+
+> #### Example
+>
+> ```python
+> ruler = nlp.add_pipe("span_ruler")
+> ruler.to_disk("/path/to/span_ruler")
+> ```
+
+| 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]~~ |
+
+## SpanRuler.from_disk {id="from_disk",tag="method"}
+
+Load the span ruler from a path.
+
+> #### Example
+>
+> ```python
+> ruler = nlp.add_pipe("span_ruler")
+> ruler.from_disk("/path/to/span_ruler")
+> ```
+
+| Name | Description |
+| ----------- | ----------------------------------------------------------------------------------------------- |
+| `path` | A path to a directory. Paths may be either strings or `Path`-like objects. ~~Union[str, Path]~~ |
+| **RETURNS** | The modified `SpanRuler` object. ~~SpanRuler~~ |
+
+## SpanRuler.to_bytes {id="to_bytes",tag="method"}
+
+Serialize the span ruler to a bytestring.
+
+> #### Example
+>
+> ```python
+> ruler = nlp.add_pipe("span_ruler")
+> ruler_bytes = ruler.to_bytes()
+> ```
+
+| Name | Description |
+| ----------- | ---------------------------------- |
+| **RETURNS** | The serialized patterns. ~~bytes~~ |
+
+## SpanRuler.from_bytes {id="from_bytes",tag="method"}
+
+Load the pipe from a bytestring. Modifies the object in place and returns it.
+
+> #### Example
+>
+> ```python
+> ruler_bytes = ruler.to_bytes()
+> ruler = nlp.add_pipe("span_ruler")
+> ruler.from_bytes(ruler_bytes)
+> ```
+
+| Name | Description |
+| ------------ | ---------------------------------------------- |
+| `bytes_data` | The bytestring to load. ~~bytes~~ |
+| **RETURNS** | The modified `SpanRuler` object. ~~SpanRuler~~ |
+
+## SpanRuler.labels {id="labels",tag="property"}
+
+All labels present in the match patterns.
+
+| Name | Description |
+| ----------- | -------------------------------------- |
+| **RETURNS** | The string labels. ~~Tuple[str, ...]~~ |
+
+## SpanRuler.ids {id="ids",tag="property"}
+
+All IDs present in the `id` property of the match patterns.
+
+| Name | Description |
+| ----------- | ----------------------------------- |
+| **RETURNS** | The string IDs. ~~Tuple[str, ...]~~ |
+
+## SpanRuler.patterns {id="patterns",tag="property"}
+
+All patterns that were added to the span ruler.
+
+| Name | Description |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| **RETURNS** | The original patterns, one dictionary per pattern. ~~List[Dict[str, Union[str, dict]]]~~ |
+
+## Attributes {id="attributes"}
+
+| Name | Description |
+| ---------------- | -------------------------------------------------------------------------------- |
+| `key` | The spans key that spans are saved under. ~~Optional[str]~~ |
+| `matcher` | The underlying matcher used to process token patterns. ~~Matcher~~ |
+| `phrase_matcher` | The underlying phrase matcher used to process phrase patterns. ~~PhraseMatcher~~ |
diff --git a/website/docs/api/stringstore.md b/website/docs/api/stringstore.mdx
similarity index 88%
rename from website/docs/api/stringstore.md
rename to website/docs/api/stringstore.mdx
index d5f78dbab..47d3715c1 100644
--- a/website/docs/api/stringstore.md
+++ b/website/docs/api/stringstore.mdx
@@ -8,7 +8,7 @@ Look up strings by 64-bit hashes. As of v2.0, spaCy uses hash values instead of
integer IDs. This ensures that strings always map to the same ID, even from
different `StringStores`.
-## StringStore.\_\_init\_\_ {#init tag="method"}
+## StringStore.\_\_init\_\_ {id="init",tag="method"}
Create the `StringStore`.
@@ -23,7 +23,7 @@ Create the `StringStore`.
| --------- | ---------------------------------------------------------------------- |
| `strings` | A sequence of strings to add to the store. ~~Optional[Iterable[str]]~~ |
-## StringStore.\_\_len\_\_ {#len tag="method"}
+## StringStore.\_\_len\_\_ {id="len",tag="method"}
Get the number of strings in the store.
@@ -38,7 +38,7 @@ Get the number of strings in the store.
| ----------- | ------------------------------------------- |
| **RETURNS** | The number of strings in the store. ~~int~~ |
-## StringStore.\_\_getitem\_\_ {#getitem tag="method"}
+## StringStore.\_\_getitem\_\_ {id="getitem",tag="method"}
Retrieve a string from a given hash, or vice versa.
@@ -56,7 +56,7 @@ Retrieve a string from a given hash, or vice versa.
| `string_or_id` | The value to encode. ~~Union[bytes, str, int]~~ |
| **RETURNS** | The value to be retrieved. ~~Union[str, int]~~ |
-## StringStore.\_\_contains\_\_ {#contains tag="method"}
+## StringStore.\_\_contains\_\_ {id="contains",tag="method"}
Check whether a string is in the store.
@@ -73,7 +73,7 @@ Check whether a string is in the store.
| `string` | The string to check. ~~str~~ |
| **RETURNS** | Whether the store contains the string. ~~bool~~ |
-## StringStore.\_\_iter\_\_ {#iter tag="method"}
+## StringStore.\_\_iter\_\_ {id="iter",tag="method"}
Iterate over the strings in the store, in order. Note that a newly initialized
store will always include an empty string `""` at position `0`.
@@ -90,7 +90,7 @@ store will always include an empty string `""` at position `0`.
| ---------- | ------------------------------ |
| **YIELDS** | A string in the store. ~~str~~ |
-## StringStore.add {#add tag="method" new="2"}
+## StringStore.add {id="add",tag="method",version="2"}
Add a string to the `StringStore`.
@@ -110,7 +110,7 @@ Add a string to the `StringStore`.
| `string` | The string to add. ~~str~~ |
| **RETURNS** | The string's hash value. ~~int~~ |
-## StringStore.to_disk {#to_disk tag="method" new="2"}
+## StringStore.to_disk {id="to_disk",tag="method",version="2"}
Save the current state to a directory.
@@ -124,7 +124,7 @@ Save the current state to a directory.
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `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]~~ |
-## StringStore.from_disk {#from_disk tag="method" new="2"}
+## StringStore.from_disk {id="from_disk",tag="method",version="2"}
Loads state from a directory. Modifies the object in place and returns it.
@@ -140,7 +140,7 @@ Loads state from a directory. Modifies the object in place and returns it.
| `path` | A path to a directory. Paths may be either strings or `Path`-like objects. ~~Union[str, Path]~~ |
| **RETURNS** | The modified `StringStore` object. ~~StringStore~~ |
-## StringStore.to_bytes {#to_bytes tag="method"}
+## StringStore.to_bytes {id="to_bytes",tag="method"}
Serialize the current state to a binary string.
@@ -154,14 +154,14 @@ Serialize the current state to a binary string.
| ----------- | ---------------------------------------------------------- |
| **RETURNS** | The serialized form of the `StringStore` object. ~~bytes~~ |
-## StringStore.from_bytes {#from_bytes tag="method"}
+## StringStore.from_bytes {id="from_bytes",tag="method"}
Load state from a binary string.
> #### Example
>
> ```python
-> fron spacy.strings import StringStore
+> from spacy.strings import StringStore
> store_bytes = stringstore.to_bytes()
> new_store = StringStore().from_bytes(store_bytes)
> ```
@@ -171,9 +171,9 @@ Load state from a binary string.
| `bytes_data` | The data to load from. ~~bytes~~ |
| **RETURNS** | The `StringStore` object. ~~StringStore~~ |
-## Utilities {#util}
+## Utilities {id="util"}
-### strings.hash_string {#hash_string tag="function"}
+### strings.hash_string {id="hash_string",tag="function"}
Get a 64-bit hash for a given string.
diff --git a/website/docs/api/tagger.md b/website/docs/api/tagger.mdx
similarity index 93%
rename from website/docs/api/tagger.md
rename to website/docs/api/tagger.mdx
index b51864d3a..ee38de81c 100644
--- a/website/docs/api/tagger.md
+++ b/website/docs/api/tagger.mdx
@@ -14,7 +14,7 @@ part-of-speech tag set.
In the pre-trained pipelines, the tag schemas vary by language; see the
[individual model pages](/models) for details.
-## Assigned Attributes {#assigned-attributes}
+## Assigned Attributes {id="assigned-attributes"}
Predictions are assigned to `Token.tag`.
@@ -23,7 +23,7 @@ Predictions are assigned to `Token.tag`.
| `Token.tag` | The part of speech (hash). ~~int~~ |
| `Token.tag_` | The part of speech. ~~str~~ |
-## Config and implementation {#config}
+## Config and implementation {id="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
@@ -51,7 +51,7 @@ architectures and their arguments and hyperparameters.
%%GITHUB_SPACY/spacy/pipeline/tagger.pyx
```
-## Tagger.\_\_init\_\_ {#init tag="method"}
+## Tagger.\_\_init\_\_ {id="init",tag="method"}
> #### Example
>
@@ -81,7 +81,7 @@ shortcut for this and instantiate the component using its string name and
| `overwrite` 3.2 | Whether existing annotation is overwritten. Defaults to `False`. ~~bool~~ |
| `scorer` 3.2 | The scoring method. Defaults to [`Scorer.score_token_attr`](/api/scorer#score_token_attr) for the attribute `"tag"`. ~~Optional[Callable]~~ |
-## Tagger.\_\_call\_\_ {#call tag="method"}
+## Tagger.\_\_call\_\_ {id="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
@@ -104,7 +104,7 @@ and all pipeline components are applied to the `Doc` in order. Both
| `doc` | The document to process. ~~Doc~~ |
| **RETURNS** | The processed document. ~~Doc~~ |
-## Tagger.pipe {#pipe tag="method"}
+## Tagger.pipe {id="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
@@ -127,13 +127,13 @@ applied to the `Doc` in order. Both [`__call__`](/api/tagger#call) and
| `batch_size` | The number of documents to buffer. Defaults to `128`. ~~int~~ |
| **YIELDS** | The processed documents in order. ~~Doc~~ |
-## Tagger.initialize {#initialize tag="method" new="3"}
+## Tagger.initialize {id="initialize",tag="method",version="3"}
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) and lets you customize
@@ -151,7 +151,7 @@ This method was previously called `begin_training`.
>
> ```python
> tagger = nlp.add_pipe("tagger")
-> tagger.initialize(lambda: [], nlp=nlp)
+> tagger.initialize(lambda: examples, nlp=nlp)
> ```
>
> ```ini
@@ -165,12 +165,12 @@ This method was previously called `begin_training`.
| Name | Description |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `get_examples` | Function that returns gold-standard annotations in the form of [`Example`](/api/example) objects. ~~Callable[[], Iterable[Example]]~~ |
+| `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]~~ |
| `labels` | The label information to add to the component, as provided by the [`label_data`](#label_data) property after initialization. To generate a reusable JSON file from your data, you should run the [`init labels`](/api/cli#init-labels) command. If no labels are provided, the `get_examples` callback is used to extract the labels from the data, which may be a lot slower. ~~Optional[Iterable[str]]~~ |
-## Tagger.predict {#predict tag="method"}
+## Tagger.predict {id="predict",tag="method"}
Apply the component's model to a batch of [`Doc`](/api/doc) objects, without
modifying them.
@@ -187,7 +187,7 @@ modifying them.
| `docs` | The documents to predict. ~~Iterable[Doc]~~ |
| **RETURNS** | The model's prediction for each document. |
-## Tagger.set_annotations {#set_annotations tag="method"}
+## Tagger.set_annotations {id="set_annotations",tag="method"}
Modify a batch of [`Doc`](/api/doc) objects, using pre-computed scores.
@@ -204,7 +204,7 @@ Modify a batch of [`Doc`](/api/doc) objects, using pre-computed scores.
| `docs` | The documents to modify. ~~Iterable[Doc]~~ |
| `scores` | The scores to set, produced by `Tagger.predict`. |
-## Tagger.update {#update tag="method"}
+## Tagger.update {id="update",tag="method"}
Learn from a batch of [`Example`](/api/example) objects containing the
predictions and gold-standard annotations, and update the component's model.
@@ -228,7 +228,7 @@ Delegates to [`predict`](/api/tagger#predict) and
| `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]~~ |
-## Tagger.rehearse {#rehearse tag="method,experimental" new="3"}
+## Tagger.rehearse {id="rehearse",tag="method,experimental",version="3"}
Perform a "rehearsal" update from a batch of data. Rehearsal updates teach the
current model to make predictions similar to an initial model, to try to address
@@ -251,7 +251,7 @@ the "catastrophic forgetting" problem. This feature is experimental.
| `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]~~ |
-## Tagger.get_loss {#get_loss tag="method"}
+## Tagger.get_loss {id="get_loss",tag="method"}
Find the loss and gradient of loss for the batch of documents and their
predicted scores.
@@ -270,7 +270,7 @@ predicted scores.
| `scores` | Scores representing the model's predictions. |
| **RETURNS** | The loss and the gradient, i.e. `(loss, gradient)`. ~~Tuple[float, float]~~ |
-## Tagger.create_optimizer {#create_optimizer tag="method"}
+## Tagger.create_optimizer {id="create_optimizer",tag="method"}
Create an optimizer for the pipeline component.
@@ -285,7 +285,7 @@ Create an optimizer for the pipeline component.
| ----------- | ---------------------------- |
| **RETURNS** | The optimizer. ~~Optimizer~~ |
-## Tagger.use_params {#use_params tag="method, contextmanager"}
+## Tagger.use_params {id="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.
@@ -302,7 +302,7 @@ context, the original parameters are restored.
| -------- | -------------------------------------------------- |
| `params` | The parameter values to use in the model. ~~dict~~ |
-## Tagger.add_label {#add_label tag="method"}
+## Tagger.add_label {id="add_label",tag="method"}
Add a new label to the pipe. Raises an error if the output dimension is already
set, or if the model has already been fully [initialized](#initialize). Note
@@ -324,7 +324,7 @@ automatically.
| `label` | The label to add. ~~str~~ |
| **RETURNS** | `0` if the label is already present, otherwise `1`. ~~int~~ |
-## Tagger.to_disk {#to_disk tag="method"}
+## Tagger.to_disk {id="to_disk",tag="method"}
Serialize the pipe to disk.
@@ -341,7 +341,7 @@ Serialize the pipe to disk.
| _keyword-only_ | |
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
-## Tagger.from_disk {#from_disk tag="method"}
+## Tagger.from_disk {id="from_disk",tag="method"}
Load the pipe from disk. Modifies the object in place and returns it.
@@ -359,7 +359,7 @@ Load the pipe from disk. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The modified `Tagger` object. ~~Tagger~~ |
-## Tagger.to_bytes {#to_bytes tag="method"}
+## Tagger.to_bytes {id="to_bytes",tag="method"}
> #### Example
>
@@ -376,7 +376,7 @@ Serialize the pipe to a bytestring.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The serialized form of the `Tagger` object. ~~bytes~~ |
-## Tagger.from_bytes {#from_bytes tag="method"}
+## Tagger.from_bytes {id="from_bytes",tag="method"}
Load the pipe from a bytestring. Modifies the object in place and returns it.
@@ -395,7 +395,7 @@ Load the pipe from a bytestring. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The `Tagger` object. ~~Tagger~~ |
-## Tagger.labels {#labels tag="property"}
+## Tagger.labels {id="labels",tag="property"}
The labels currently added to the component.
@@ -410,7 +410,7 @@ The labels currently added to the component.
| ----------- | ------------------------------------------------------ |
| **RETURNS** | The labels added to the component. ~~Tuple[str, ...]~~ |
-## Tagger.label_data {#label_data tag="property" new="3"}
+## Tagger.label_data {id="label_data",tag="property",version="3"}
The labels currently added to the component and their internal meta information.
This is the data generated by [`init labels`](/api/cli#init-labels) and used by
@@ -428,7 +428,7 @@ pre-defined label set.
| ----------- | ---------------------------------------------------------- |
| **RETURNS** | The label data added to the component. ~~Tuple[str, ...]~~ |
-## Serialization fields {#serialization-fields}
+## Serialization fields {id="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
diff --git a/website/docs/api/textcategorizer.md b/website/docs/api/textcategorizer.mdx
similarity index 91%
rename from website/docs/api/textcategorizer.md
rename to website/docs/api/textcategorizer.mdx
index 2ff569bad..a259b7b3c 100644
--- a/website/docs/api/textcategorizer.md
+++ b/website/docs/api/textcategorizer.mdx
@@ -2,7 +2,7 @@
title: TextCategorizer
tag: class
source: spacy/pipeline/textcat.py
-new: 2
+version: 2
teaser: 'Pipeline component for text classification'
api_base_class: /api/pipe
api_string_name: textcat
@@ -29,7 +29,7 @@ only.
-## Assigned Attributes {#assigned-attributes}
+## Assigned Attributes {id="assigned-attributes"}
Predictions will be saved to `doc.cats` as a dictionary, where the key is the
name of the category and the value is a score between 0 and 1 (inclusive). For
@@ -49,7 +49,7 @@ supported.
| ---------- | ------------------------------------- |
| `Doc.cats` | Category scores. ~~Dict[str, float]~~ |
-## Config and implementation {#config}
+## Config and implementation {id="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
@@ -63,7 +63,6 @@ architectures and their arguments and hyperparameters.
> ```python
> from spacy.pipeline.textcat import DEFAULT_SINGLE_TEXTCAT_MODEL
> config = {
-> "threshold": 0.5,
> "model": DEFAULT_SINGLE_TEXTCAT_MODEL,
> }
> nlp.add_pipe("textcat", config=config)
@@ -82,8 +81,9 @@ architectures and their arguments and hyperparameters.
| Setting | Description |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `threshold` | Cutoff to consider a prediction "positive", relevant when printing accuracy results. ~~float~~ |
+| `threshold` | Cutoff to consider a prediction "positive", relevant for `textcat_multilabel` when calculating accuracy scores. ~~float~~ |
| `model` | A model instance that predicts scores for each category. Defaults to [TextCatEnsemble](/api/architectures#TextCatEnsemble). ~~Model[List[Doc], List[Floats2d]]~~ |
+| `scorer` | The scoring method. Defaults to [`Scorer.score_cats`](/api/scorer#score_cats) for the attribute `"cats"`. ~~Optional[Callable]~~ |
```python
%%GITHUB_SPACY/spacy/pipeline/textcat.py
@@ -93,7 +93,7 @@ architectures and their arguments and hyperparameters.
%%GITHUB_SPACY/spacy/pipeline/textcat_multilabel.py
```
-## TextCategorizer.\_\_init\_\_ {#init tag="method"}
+## TextCategorizer.\_\_init\_\_ {id="init",tag="method"}
> #### Example
>
@@ -122,10 +122,10 @@ shortcut for this and instantiate the component using its string name and
| `model` | The Thinc [`Model`](https://thinc.ai/docs/api-model) powering the pipeline component. ~~Model[List[Doc], List[Floats2d]]~~ |
| `name` | String name of the component instance. Used to add entries to the `losses` during training. ~~str~~ |
| _keyword-only_ | |
-| `threshold` | Cutoff to consider a prediction "positive", relevant when printing accuracy results. ~~float~~ |
+| `threshold` | Cutoff to consider a prediction "positive", relevant for `textcat_multilabel` when calculating accuracy scores. ~~float~~ |
| `scorer` | The scoring method. Defaults to [`Scorer.score_cats`](/api/scorer#score_cats) for the attribute `"cats"`. ~~Optional[Callable]~~ |
-## TextCategorizer.\_\_call\_\_ {#call tag="method"}
+## TextCategorizer.\_\_call\_\_ {id="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
@@ -148,7 +148,7 @@ delegate to the [`predict`](/api/textcategorizer#predict) and
| `doc` | The document to process. ~~Doc~~ |
| **RETURNS** | The processed document. ~~Doc~~ |
-## TextCategorizer.pipe {#pipe tag="method"}
+## TextCategorizer.pipe {id="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
@@ -172,13 +172,13 @@ applied to the `Doc` in order. Both [`__call__`](/api/textcategorizer#call) and
| `batch_size` | The number of documents to buffer. Defaults to `128`. ~~int~~ |
| **YIELDS** | The processed documents in order. ~~Doc~~ |
-## TextCategorizer.initialize {#initialize tag="method" new="3"}
+## TextCategorizer.initialize {id="initialize",tag="method",version="3"}
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) and lets you customize
@@ -196,7 +196,7 @@ This method was previously called `begin_training`.
>
> ```python
> textcat = nlp.add_pipe("textcat")
-> textcat.initialize(lambda: [], nlp=nlp)
+> textcat.initialize(lambda: examples, nlp=nlp)
> ```
>
> ```ini
@@ -211,13 +211,13 @@ This method was previously called `begin_training`.
| Name | Description |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `get_examples` | Function that returns gold-standard annotations in the form of [`Example`](/api/example) objects. ~~Callable[[], Iterable[Example]]~~ |
+| `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]~~ |
| `labels` | The label information to add to the component, as provided by the [`label_data`](#label_data) property after initialization. To generate a reusable JSON file from your data, you should run the [`init labels`](/api/cli#init-labels) command. If no labels are provided, the `get_examples` callback is used to extract the labels from the data, which may be a lot slower. ~~Optional[Iterable[str]]~~ |
| `positive_label` | The positive label for a binary task with exclusive classes, `None` otherwise and by default. This parameter is only used during scoring. It is not available when using the `textcat_multilabel` component. ~~Optional[str]~~ |
-## TextCategorizer.predict {#predict tag="method"}
+## TextCategorizer.predict {id="predict",tag="method"}
Apply the component's model to a batch of [`Doc`](/api/doc) objects without
modifying them.
@@ -234,7 +234,7 @@ modifying them.
| `docs` | The documents to predict. ~~Iterable[Doc]~~ |
| **RETURNS** | The model's prediction for each document. |
-## TextCategorizer.set_annotations {#set_annotations tag="method"}
+## TextCategorizer.set_annotations {id="set_annotations",tag="method"}
Modify a batch of [`Doc`](/api/doc) objects using pre-computed scores.
@@ -251,7 +251,7 @@ Modify a batch of [`Doc`](/api/doc) objects using pre-computed scores.
| `docs` | The documents to modify. ~~Iterable[Doc]~~ |
| `scores` | The scores to set, produced by `TextCategorizer.predict`. |
-## TextCategorizer.update {#update tag="method"}
+## TextCategorizer.update {id="update",tag="method"}
Learn from a batch of [`Example`](/api/example) objects containing the
predictions and gold-standard annotations, and update the component's model.
@@ -275,7 +275,7 @@ Delegates to [`predict`](/api/textcategorizer#predict) and
| `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]~~ |
-## TextCategorizer.rehearse {#rehearse tag="method,experimental" new="3"}
+## TextCategorizer.rehearse {id="rehearse",tag="method,experimental",version="3"}
Perform a "rehearsal" update from a batch of data. Rehearsal updates teach the
current model to make predictions similar to an initial model to try to address
@@ -298,7 +298,7 @@ the "catastrophic forgetting" problem. This feature is experimental.
| `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]~~ |
-## TextCategorizer.get_loss {#get_loss tag="method"}
+## TextCategorizer.get_loss {id="get_loss",tag="method"}
Find the loss and gradient of loss for the batch of documents and their
predicted scores.
@@ -317,7 +317,7 @@ predicted scores.
| `scores` | Scores representing the model's predictions. |
| **RETURNS** | The loss and the gradient, i.e. `(loss, gradient)`. ~~Tuple[float, float]~~ |
-## TextCategorizer.score {#score tag="method" new="3"}
+## TextCategorizer.score {id="score",tag="method",version="3"}
Score a batch of examples.
@@ -333,7 +333,7 @@ Score a batch of examples.
| _keyword-only_ | |
| **RETURNS** | The scores, produced by [`Scorer.score_cats`](/api/scorer#score_cats). ~~Dict[str, Union[float, Dict[str, float]]]~~ |
-## TextCategorizer.create_optimizer {#create_optimizer tag="method"}
+## TextCategorizer.create_optimizer {id="create_optimizer",tag="method"}
Create an optimizer for the pipeline component.
@@ -348,7 +348,7 @@ Create an optimizer for the pipeline component.
| ----------- | ---------------------------- |
| **RETURNS** | The optimizer. ~~Optimizer~~ |
-## TextCategorizer.use_params {#use_params tag="method, contextmanager"}
+## TextCategorizer.use_params {id="use_params",tag="method, contextmanager"}
Modify the pipe's model to use the given parameter values.
@@ -364,7 +364,7 @@ Modify the pipe's model to use the given parameter values.
| -------- | -------------------------------------------------- |
| `params` | The parameter values to use in the model. ~~dict~~ |
-## TextCategorizer.add_label {#add_label tag="method"}
+## TextCategorizer.add_label {id="add_label",tag="method"}
Add a new label to the pipe. Raises an error if the output dimension is already
set, or if the model has already been fully [initialized](#initialize). Note
@@ -386,7 +386,7 @@ automatically.
| `label` | The label to add. ~~str~~ |
| **RETURNS** | `0` if the label is already present, otherwise `1`. ~~int~~ |
-## TextCategorizer.to_disk {#to_disk tag="method"}
+## TextCategorizer.to_disk {id="to_disk",tag="method"}
Serialize the pipe to disk.
@@ -403,7 +403,7 @@ Serialize the pipe to disk.
| _keyword-only_ | |
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
-## TextCategorizer.from_disk {#from_disk tag="method"}
+## TextCategorizer.from_disk {id="from_disk",tag="method"}
Load the pipe from disk. Modifies the object in place and returns it.
@@ -421,7 +421,7 @@ Load the pipe from disk. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The modified `TextCategorizer` object. ~~TextCategorizer~~ |
-## TextCategorizer.to_bytes {#to_bytes tag="method"}
+## TextCategorizer.to_bytes {id="to_bytes",tag="method"}
> #### Example
>
@@ -438,7 +438,7 @@ Serialize the pipe to a bytestring.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The serialized form of the `TextCategorizer` object. ~~bytes~~ |
-## TextCategorizer.from_bytes {#from_bytes tag="method"}
+## TextCategorizer.from_bytes {id="from_bytes",tag="method"}
Load the pipe from a bytestring. Modifies the object in place and returns it.
@@ -457,7 +457,7 @@ Load the pipe from a bytestring. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The `TextCategorizer` object. ~~TextCategorizer~~ |
-## TextCategorizer.labels {#labels tag="property"}
+## TextCategorizer.labels {id="labels",tag="property"}
The labels currently added to the component.
@@ -472,7 +472,7 @@ The labels currently added to the component.
| ----------- | ------------------------------------------------------ |
| **RETURNS** | The labels added to the component. ~~Tuple[str, ...]~~ |
-## TextCategorizer.label_data {#label_data tag="property" new="3"}
+## TextCategorizer.label_data {id="label_data",tag="property",version="3"}
The labels currently added to the component and their internal meta information.
This is the data generated by [`init labels`](/api/cli#init-labels) and used by
@@ -490,7 +490,7 @@ the model with a pre-defined label set.
| ----------- | ---------------------------------------------------------- |
| **RETURNS** | The label data added to the component. ~~Tuple[str, ...]~~ |
-## Serialization fields {#serialization-fields}
+## Serialization fields {id="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
diff --git a/website/docs/api/tok2vec.md b/website/docs/api/tok2vec.mdx
similarity index 90%
rename from website/docs/api/tok2vec.md
rename to website/docs/api/tok2vec.mdx
index 70c352b4d..a1bb1265e 100644
--- a/website/docs/api/tok2vec.md
+++ b/website/docs/api/tok2vec.mdx
@@ -1,7 +1,7 @@
---
title: Tok2Vec
source: spacy/pipeline/tok2vec.py
-new: 3
+version: 3
teaser: null
api_base_class: /api/pipe
api_string_name: tok2vec
@@ -23,7 +23,7 @@ components can backpropagate to the shared weights. This implementation is used
because it allows us to avoid relying on object identity within the models to
achieve the parameter sharing.
-## Config and implementation {#config}
+## Config and implementation {id="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
@@ -48,7 +48,7 @@ architectures and their arguments and hyperparameters.
%%GITHUB_SPACY/spacy/pipeline/tok2vec.py
```
-## Tok2Vec.\_\_init\_\_ {#init tag="method"}
+## Tok2Vec.\_\_init\_\_ {id="init",tag="method"}
> #### Example
>
@@ -75,7 +75,7 @@ shortcut for this and instantiate the component using its string name and
| `model` | The Thinc [`Model`](https://thinc.ai/docs/api-model) powering the pipeline component. ~~Model[List[Doc], List[Floats2d]~~ |
| `name` | String name of the component instance. Used to add entries to the `losses` during training. ~~str~~ |
-## Tok2Vec.\_\_call\_\_ {#call tag="method"}
+## Tok2Vec.\_\_call\_\_ {id="call",tag="method"}
Apply the pipe to one document and add context-sensitive embeddings to the
`Doc.tensor` attribute, allowing them to be used as features by downstream
@@ -100,7 +100,7 @@ pipeline components are applied to the `Doc` in order. Both
| `doc` | The document to process. ~~Doc~~ |
| **RETURNS** | The processed document. ~~Doc~~ |
-## Tok2Vec.pipe {#pipe tag="method"}
+## Tok2Vec.pipe {id="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
@@ -123,14 +123,14 @@ and [`set_annotations`](/api/tok2vec#set_annotations) methods.
| `batch_size` | The number of documents to buffer. Defaults to `128`. ~~int~~ |
| **YIELDS** | The processed documents in order. ~~Doc~~ |
-## Tok2Vec.initialize {#initialize tag="method"}
+## Tok2Vec.initialize {id="initialize",tag="method"}
Initialize the component for training and return an
[`Optimizer`](https://thinc.ai/docs/api-optimizers). `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,
+function that 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).
@@ -139,16 +139,16 @@ by [`Language.initialize`](/api/language#initialize).
>
> ```python
> tok2vec = nlp.add_pipe("tok2vec")
-> tok2vec.initialize(lambda: [], nlp=nlp)
+> tok2vec.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]~~ |
-## Tok2Vec.predict {#predict tag="method"}
+## Tok2Vec.predict {id="predict",tag="method"}
Apply the component's model to a batch of [`Doc`](/api/doc) objects without
modifying them.
@@ -165,7 +165,7 @@ modifying them.
| `docs` | The documents to predict. ~~Iterable[Doc]~~ |
| **RETURNS** | The model's prediction for each document. |
-## Tok2Vec.set_annotations {#set_annotations tag="method"}
+## Tok2Vec.set_annotations {id="set_annotations",tag="method"}
Modify a batch of [`Doc`](/api/doc) objects, using pre-computed scores.
@@ -182,7 +182,7 @@ Modify a batch of [`Doc`](/api/doc) objects, using pre-computed scores.
| `docs` | The documents to modify. ~~Iterable[Doc]~~ |
| `scores` | The scores to set, produced by `Tok2Vec.predict`. |
-## Tok2Vec.update {#update tag="method"}
+## Tok2Vec.update {id="update",tag="method"}
Learn from a batch of [`Example`](/api/example) objects containing the
predictions and gold-standard annotations, and update the component's model.
@@ -205,7 +205,7 @@ Delegates to [`predict`](/api/tok2vec#predict).
| `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]~~ |
-## Tok2Vec.create_optimizer {#create_optimizer tag="method"}
+## Tok2Vec.create_optimizer {id="create_optimizer",tag="method"}
Create an optimizer for the pipeline component.
@@ -220,7 +220,7 @@ Create an optimizer for the pipeline component.
| ----------- | ---------------------------- |
| **RETURNS** | The optimizer. ~~Optimizer~~ |
-## Tok2Vec.use_params {#use_params tag="method, contextmanager"}
+## Tok2Vec.use_params {id="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.
@@ -237,7 +237,7 @@ context, the original parameters are restored.
| -------- | -------------------------------------------------- |
| `params` | The parameter values to use in the model. ~~dict~~ |
-## Tok2Vec.to_disk {#to_disk tag="method"}
+## Tok2Vec.to_disk {id="to_disk",tag="method"}
Serialize the pipe to disk.
@@ -254,7 +254,7 @@ Serialize the pipe to disk.
| _keyword-only_ | |
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
-## Tok2Vec.from_disk {#from_disk tag="method"}
+## Tok2Vec.from_disk {id="from_disk",tag="method"}
Load the pipe from disk. Modifies the object in place and returns it.
@@ -272,7 +272,7 @@ Load the pipe from disk. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The modified `Tok2Vec` object. ~~Tok2Vec~~ |
-## Tok2Vec.to_bytes {#to_bytes tag="method"}
+## Tok2Vec.to_bytes {id="to_bytes",tag="method"}
> #### Example
>
@@ -289,7 +289,7 @@ Serialize the pipe to a bytestring.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The serialized form of the `Tok2Vec` object. ~~bytes~~ |
-## Tok2Vec.from_bytes {#from_bytes tag="method"}
+## Tok2Vec.from_bytes {id="from_bytes",tag="method"}
Load the pipe from a bytestring. Modifies the object in place and returns it.
@@ -308,7 +308,7 @@ Load the pipe from a bytestring. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The `Tok2Vec` object. ~~Tok2Vec~~ |
-## Serialization fields {#serialization-fields}
+## Serialization fields {id="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
diff --git a/website/docs/api/token.md b/website/docs/api/token.mdx
similarity index 56%
rename from website/docs/api/token.md
rename to website/docs/api/token.mdx
index 3c3d12d54..63ee1080b 100644
--- a/website/docs/api/token.md
+++ b/website/docs/api/token.mdx
@@ -5,7 +5,7 @@ tag: class
source: spacy/tokens/token.pyx
---
-## Token.\_\_init\_\_ {#init tag="method"}
+## Token.\_\_init\_\_ {id="init",tag="method"}
Construct a `Token` object.
@@ -23,7 +23,7 @@ Construct a `Token` object.
| `doc` | The parent document. ~~Doc~~ |
| `offset` | The index of the token within the document. ~~int~~ |
-## Token.\_\_len\_\_ {#len tag="method"}
+## Token.\_\_len\_\_ {id="len",tag="method"}
The number of unicode characters in the token, i.e. `token.text`.
@@ -39,7 +39,7 @@ The number of unicode characters in the token, i.e. `token.text`.
| ----------- | ------------------------------------------------------ |
| **RETURNS** | The number of unicode characters in the token. ~~int~~ |
-## Token.set_extension {#set_extension tag="classmethod" new="2"}
+## Token.set_extension {id="set_extension",tag="classmethod",version="2"}
Define a custom attribute on the `Token` which becomes available via `Token._`.
For details, see the documentation on
@@ -64,7 +64,7 @@ For details, see the documentation on
| `setter` | Setter function that takes the `Token` and a value, and modifies the object. Is called when the user writes to the `Token._` attribute. ~~Optional[Callable[[Token, Any], None]]~~ |
| `force` | Force overwriting existing attribute. ~~bool~~ |
-## Token.get_extension {#get_extension tag="classmethod" new="2"}
+## Token.get_extension {id="get_extension",tag="classmethod",version="2"}
Look up a previously registered extension by name. Returns a 4-tuple
`(default, method, getter, setter)` if the extension is registered. Raises a
@@ -84,7 +84,7 @@ Look up a previously registered extension by name. Returns a 4-tuple
| `name` | Name of the extension. ~~str~~ |
| **RETURNS** | A `(default, method, getter, setter)` tuple of the extension. ~~Tuple[Optional[Any], Optional[Callable], Optional[Callable], Optional[Callable]]~~ |
-## Token.has_extension {#has_extension tag="classmethod" new="2"}
+## Token.has_extension {id="has_extension",tag="classmethod",version="2"}
Check whether an extension has been registered on the `Token` class.
@@ -101,7 +101,7 @@ Check whether an extension has been registered on the `Token` class.
| `name` | Name of the extension to check. ~~str~~ |
| **RETURNS** | Whether the extension has been registered. ~~bool~~ |
-## Token.remove_extension {#remove_extension tag="classmethod" new=""2.0.11""}
+## Token.remove_extension {id="remove_extension",tag="classmethod",version="2.0.11"}
Remove a previously registered extension.
@@ -119,7 +119,7 @@ Remove a previously registered extension.
| `name` | Name of the extension. ~~str~~ |
| **RETURNS** | A `(default, method, getter, setter)` tuple of the removed extension. ~~Tuple[Optional[Any], Optional[Callable], Optional[Callable], Optional[Callable]]~~ |
-## Token.check_flag {#check_flag tag="method"}
+## Token.check_flag {id="check_flag",tag="method"}
Check the value of a boolean flag.
@@ -137,7 +137,7 @@ Check the value of a boolean flag.
| `flag_id` | The attribute ID of the flag to check. ~~int~~ |
| **RETURNS** | Whether the flag is set. ~~bool~~ |
-## Token.similarity {#similarity tag="method" model="vectors"}
+## Token.similarity {id="similarity",tag="method",model="vectors"}
Compute a semantic similarity estimate. Defaults to cosine over vectors.
@@ -155,7 +155,7 @@ Compute a semantic similarity estimate. Defaults to cosine over vectors.
| other | The object to compare with. By default, accepts `Doc`, `Span`, `Token` and `Lexeme` objects. ~~Union[Doc, Span, Token, Lexeme]~~ |
| **RETURNS** | A scalar similarity score. Higher is more similar. ~~float~~ |
-## Token.nbor {#nbor tag="method"}
+## Token.nbor {id="nbor",tag="method"}
Get a neighboring token.
@@ -172,7 +172,7 @@ Get a neighboring token.
| `i` | The relative position of the token to get. Defaults to `1`. ~~int~~ |
| **RETURNS** | The token at position `self.doc[self.i+i]`. ~~Token~~ |
-## Token.set_morph {#set_morph tag="method"}
+## Token.set_morph {id="set_morph",tag="method"}
Set the morphological analysis from a UD FEATS string, hash value of a UD FEATS
string, features dict or `MorphAnalysis`. The value `None` can be used to reset
@@ -191,7 +191,7 @@ the morph to an unset state.
| -------- | --------------------------------------------------------------------------------- |
| features | The morphological features to set. ~~Union[int, dict, str, MorphAnalysis, None]~~ |
-## Token.has_morph {#has_morph tag="method"}
+## Token.has_morph {id="has_morph",tag="method"}
Check whether the token has annotated morph information. Return `False` when the
morph annotation is unset/missing.
@@ -200,7 +200,7 @@ morph annotation is unset/missing.
| ----------- | --------------------------------------------- |
| **RETURNS** | Whether the morph annotation is set. ~~bool~~ |
-## Token.is_ancestor {#is_ancestor tag="method" model="parser"}
+## Token.is_ancestor {id="is_ancestor",tag="method",model="parser"}
Check whether this token is a parent, grandparent, etc. of another in the
dependency tree.
@@ -219,9 +219,9 @@ dependency tree.
| descendant | Another token. ~~Token~~ |
| **RETURNS** | Whether this token is the ancestor of the descendant. ~~bool~~ |
-## Token.ancestors {#ancestors tag="property" model="parser"}
+## Token.ancestors {id="ancestors",tag="property",model="parser"}
-The rightmost token of this token's syntactic descendants.
+A sequence of the token's syntactic ancestors (parents, grandparents, etc).
> #### Example
>
@@ -237,7 +237,7 @@ The rightmost token of this token's syntactic descendants.
| ---------- | ------------------------------------------------------------------------------- |
| **YIELDS** | A sequence of ancestor tokens such that `ancestor.is_ancestor(self)`. ~~Token~~ |
-## Token.conjuncts {#conjuncts tag="property" model="parser"}
+## Token.conjuncts {id="conjuncts",tag="property",model="parser"}
A tuple of coordinated tokens, not including the token itself.
@@ -253,7 +253,7 @@ A tuple of coordinated tokens, not including the token itself.
| ----------- | --------------------------------------------- |
| **RETURNS** | The coordinated tokens. ~~Tuple[Token, ...]~~ |
-## Token.children {#children tag="property" model="parser"}
+## Token.children {id="children",tag="property",model="parser"}
A sequence of the token's immediate syntactic children.
@@ -269,7 +269,7 @@ A sequence of the token's immediate syntactic children.
| ---------- | ------------------------------------------------------- |
| **YIELDS** | A child token such that `child.head == self`. ~~Token~~ |
-## Token.lefts {#lefts tag="property" model="parser"}
+## Token.lefts {id="lefts",tag="property",model="parser"}
The leftward immediate children of the word in the syntactic dependency parse.
@@ -285,7 +285,7 @@ The leftward immediate children of the word in the syntactic dependency parse.
| ---------- | ------------------------------------ |
| **YIELDS** | A left-child of the token. ~~Token~~ |
-## Token.rights {#rights tag="property" model="parser"}
+## Token.rights {id="rights",tag="property",model="parser"}
The rightward immediate children of the word in the syntactic dependency parse.
@@ -301,7 +301,7 @@ The rightward immediate children of the word in the syntactic dependency parse.
| ---------- | ------------------------------------- |
| **YIELDS** | A right-child of the token. ~~Token~~ |
-## Token.n_lefts {#n_lefts tag="property" model="parser"}
+## Token.n_lefts {id="n_lefts",tag="property",model="parser"}
The number of leftward immediate children of the word in the syntactic
dependency parse.
@@ -317,7 +317,7 @@ dependency parse.
| ----------- | ---------------------------------------- |
| **RETURNS** | The number of left-child tokens. ~~int~~ |
-## Token.n_rights {#n_rights tag="property" model="parser"}
+## Token.n_rights {id="n_rights",tag="property",model="parser"}
The number of rightward immediate children of the word in the syntactic
dependency parse.
@@ -333,7 +333,7 @@ dependency parse.
| ----------- | ----------------------------------------- |
| **RETURNS** | The number of right-child tokens. ~~int~~ |
-## Token.subtree {#subtree tag="property" model="parser"}
+## Token.subtree {id="subtree",tag="property",model="parser"}
A sequence containing the token and all the token's syntactic descendants.
@@ -349,7 +349,7 @@ A sequence containing the token and all the token's syntactic descendants.
| ---------- | ------------------------------------------------------------------------------------ |
| **YIELDS** | A descendant token such that `self.is_ancestor(token)` or `token == self`. ~~Token~~ |
-## Token.has_vector {#has_vector tag="property" model="vectors"}
+## Token.has_vector {id="has_vector",tag="property",model="vectors"}
A boolean value indicating whether a word vector is associated with the token.
@@ -365,7 +365,7 @@ A boolean value indicating whether a word vector is associated with the token.
| ----------- | ------------------------------------------------------ |
| **RETURNS** | Whether the token has a vector data attached. ~~bool~~ |
-## Token.vector {#vector tag="property" model="vectors"}
+## Token.vector {id="vector",tag="property",model="vectors"}
A real-valued meaning representation.
@@ -382,7 +382,7 @@ A real-valued meaning representation.
| ----------- | ----------------------------------------------------------------------------------------------- |
| **RETURNS** | A 1-dimensional array representing the token's vector. ~~numpy.ndarray[ndim=1, dtype=float32]~~ |
-## Token.vector_norm {#vector_norm tag="property" model="vectors"}
+## Token.vector_norm {id="vector_norm",tag="property",model="vectors"}
The L2 norm of the token's vector representation.
@@ -401,77 +401,77 @@ The L2 norm of the token's vector representation.
| ----------- | --------------------------------------------------- |
| **RETURNS** | The L2 norm of the vector representation. ~~float~~ |
-## Attributes {#attributes}
+## Attributes {id="attributes"}
-| Name | Description |
-| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `doc` | The parent document. ~~Doc~~ |
-| `lex` 3 | The underlying lexeme. ~~Lexeme~~ |
-| `sent` 2.0.12 | The sentence span that this token is a part of. ~~Span~~ |
-| `text` | Verbatim text content. ~~str~~ |
-| `text_with_ws` | Text content, with trailing space character if present. ~~str~~ |
-| `whitespace_` | Trailing space character if present. ~~str~~ |
-| `orth` | ID of the verbatim text content. ~~int~~ |
-| `orth_` | Verbatim text content (identical to `Token.text`). Exists mostly for consistency with the other attributes. ~~str~~ |
-| `vocab` | The vocab object of the parent `Doc`. ~~vocab~~ |
-| `tensor` 2.1.7 | The token's slice of the parent `Doc`'s tensor. ~~numpy.ndarray~~ |
-| `head` | The syntactic parent, or "governor", of this token. ~~Token~~ |
-| `left_edge` | The leftmost token of this token's syntactic descendants. ~~Token~~ |
-| `right_edge` | The rightmost token of this token's syntactic descendants. ~~Token~~ |
-| `i` | The index of the token within the parent document. ~~int~~ |
-| `ent_type` | Named entity type. ~~int~~ |
-| `ent_type_` | Named entity type. ~~str~~ |
-| `ent_iob` | IOB code of named entity tag. `3` means the token begins an entity, `2` means it is outside an entity, `1` means it is inside an entity, and `0` means no entity tag is set. ~~int~~ |
-| `ent_iob_` | IOB code of named entity tag. "B" means the token begins an entity, "I" means it is inside an entity, "O" means it is outside an entity, and "" means no entity tag is set. ~~str~~ |
-| `ent_kb_id` 2.2 | Knowledge base ID that refers to the named entity this token is a part of, if any. ~~int~~ |
-| `ent_kb_id_` 2.2 | Knowledge base ID that refers to the named entity this token is a part of, if any. ~~str~~ |
-| `ent_id` | ID of the entity the token is an instance of, if any. Currently not used, but potentially for coreference resolution. ~~int~~ |
-| `ent_id_` | ID of the entity the token is an instance of, if any. Currently not used, but potentially for coreference resolution. ~~str~~ |
-| `lemma` | Base form of the token, with no inflectional suffixes. ~~int~~ |
-| `lemma_` | Base form of the token, with no inflectional suffixes. ~~str~~ |
-| `norm` | The token's norm, i.e. a normalized form of the token text. Can be set in the language's [tokenizer exceptions](/usage/linguistic-features#language-data). ~~int~~ |
-| `norm_` | The token's norm, i.e. a normalized form of the token text. Can be set in the language's [tokenizer exceptions](/usage/linguistic-features#language-data). ~~str~~ |
-| `lower` | Lowercase form of the token. ~~int~~ |
-| `lower_` | Lowercase form of the token text. Equivalent to `Token.text.lower()`. ~~str~~ |
-| `shape` | Transform of the token's string to show orthographic features. Alphabetic characters are replaced by `x` or `X`, and numeric characters are replaced by `d`, and sequences of the same character are truncated after length 4. For example,`"Xxxx"`or`"dd"`. ~~int~~ |
-| `shape_` | Transform of the token's string to show orthographic features. Alphabetic characters are replaced by `x` or `X`, and numeric characters are replaced by `d`, and sequences of the same character are truncated after length 4. For example,`"Xxxx"`or`"dd"`. ~~str~~ |
-| `prefix` | Hash value of a length-N substring from the start of the token. Defaults to `N=1`. ~~int~~ |
-| `prefix_` | A length-N substring from the start of the token. Defaults to `N=1`. ~~str~~ |
-| `suffix` | Hash value of a length-N substring from the end of the token. Defaults to `N=3`. ~~int~~ |
-| `suffix_` | Length-N substring from the end of the token. Defaults to `N=3`. ~~str~~ |
-| `is_alpha` | Does the token consist of alphabetic characters? Equivalent to `token.text.isalpha()`. ~~bool~~ |
-| `is_ascii` | Does the token consist of ASCII characters? Equivalent to `all(ord(c) < 128 for c in token.text)`. ~~bool~~ |
-| `is_digit` | Does the token consist of digits? Equivalent to `token.text.isdigit()`. ~~bool~~ |
-| `is_lower` | Is the token in lowercase? Equivalent to `token.text.islower()`. ~~bool~~ |
-| `is_upper` | Is the token in uppercase? Equivalent to `token.text.isupper()`. ~~bool~~ |
-| `is_title` | Is the token in titlecase? Equivalent to `token.text.istitle()`. ~~bool~~ |
-| `is_punct` | Is the token punctuation? ~~bool~~ |
-| `is_left_punct` | Is the token a left punctuation mark, e.g. `"("` ? ~~bool~~ |
-| `is_right_punct` | Is the token a right punctuation mark, e.g. `")"` ? ~~bool~~ |
-| `is_sent_start` | Does the token start a sentence? ~~bool~~ or `None` if unknown. Defaults to `True` for the first token in the `Doc`. |
-| `is_sent_end` | Does the token end a sentence? ~~bool~~ or `None` if unknown. |
-| `is_space` | Does the token consist of whitespace characters? Equivalent to `token.text.isspace()`. ~~bool~~ |
-| `is_bracket` | Is the token a bracket? ~~bool~~ |
-| `is_quote` | Is the token a quotation mark? ~~bool~~ |
-| `is_currency` 2.0.8 | Is the token a currency symbol? ~~bool~~ |
-| `like_url` | Does the token resemble a URL? ~~bool~~ |
-| `like_num` | Does the token represent a number? e.g. "10.9", "10", "ten", etc. ~~bool~~ |
-| `like_email` | Does the token resemble an email address? ~~bool~~ |
-| `is_oov` | Is the token out-of-vocabulary (i.e. does it not have a word vector)? ~~bool~~ |
-| `is_stop` | Is the token part of a "stop list"? ~~bool~~ |
-| `pos` | Coarse-grained part-of-speech from the [Universal POS tag set](https://universaldependencies.org/u/pos/). ~~int~~ |
-| `pos_` | Coarse-grained part-of-speech from the [Universal POS tag set](https://universaldependencies.org/u/pos/). ~~str~~ |
-| `tag` | Fine-grained part-of-speech. ~~int~~ |
-| `tag_` | Fine-grained part-of-speech. ~~str~~ |
-| `morph` 3 | Morphological analysis. ~~MorphAnalysis~~ |
-| `dep` | Syntactic dependency relation. ~~int~~ |
-| `dep_` | Syntactic dependency relation. ~~str~~ |
-| `lang` | Language of the parent document's vocabulary. ~~int~~ |
-| `lang_` | Language of the parent document's vocabulary. ~~str~~ |
-| `prob` | Smoothed log probability estimate of token's word type (context-independent entry in the vocabulary). ~~float~~ |
-| `idx` | The character offset of the token within the parent document. ~~int~~ |
-| `sentiment` | A scalar value indicating the positivity or negativity of the token. ~~float~~ |
-| `lex_id` | Sequential ID of the token's lexical type, used to index into tables, e.g. for word vectors. ~~int~~ |
-| `rank` | Sequential ID of the token's lexical type, used to index into tables, e.g. for word vectors. ~~int~~ |
-| `cluster` | Brown cluster ID. ~~int~~ |
-| `_` | User space for adding custom [attribute extensions](/usage/processing-pipelines#custom-components-attributes). ~~Underscore~~ |
+| Name | Description |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `doc` | The parent document. ~~Doc~~ |
+| `lex` 3 | The underlying lexeme. ~~Lexeme~~ |
+| `sent` | The sentence span that this token is a part of. ~~Span~~ |
+| `text` | Verbatim text content. ~~str~~ |
+| `text_with_ws` | Text content, with trailing space character if present. ~~str~~ |
+| `whitespace_` | Trailing space character if present. ~~str~~ |
+| `orth` | ID of the verbatim text content. ~~int~~ |
+| `orth_` | Verbatim text content (identical to `Token.text`). Exists mostly for consistency with the other attributes. ~~str~~ |
+| `vocab` | The vocab object of the parent `Doc`. ~~vocab~~ |
+| `tensor` | The token's slice of the parent `Doc`'s tensor. ~~numpy.ndarray~~ |
+| `head` | The syntactic parent, or "governor", of this token. ~~Token~~ |
+| `left_edge` | The leftmost token of this token's syntactic descendants. ~~Token~~ |
+| `right_edge` | The rightmost token of this token's syntactic descendants. ~~Token~~ |
+| `i` | The index of the token within the parent document. ~~int~~ |
+| `ent_type` | Named entity type. ~~int~~ |
+| `ent_type_` | Named entity type. ~~str~~ |
+| `ent_iob` | IOB code of named entity tag. `3` means the token begins an entity, `2` means it is outside an entity, `1` means it is inside an entity, and `0` means no entity tag is set. ~~int~~ |
+| `ent_iob_` | IOB code of named entity tag. "B" means the token begins an entity, "I" means it is inside an entity, "O" means it is outside an entity, and "" means no entity tag is set. ~~str~~ |
+| `ent_kb_id` | Knowledge base ID that refers to the named entity this token is a part of, if any. ~~int~~ |
+| `ent_kb_id_` | Knowledge base ID that refers to the named entity this token is a part of, if any. ~~str~~ |
+| `ent_id` | ID of the entity the token is an instance of, if any. Currently not used, but potentially for coreference resolution. ~~int~~ |
+| `ent_id_` | ID of the entity the token is an instance of, if any. Currently not used, but potentially for coreference resolution. ~~str~~ |
+| `lemma` | Base form of the token, with no inflectional suffixes. ~~int~~ |
+| `lemma_` | Base form of the token, with no inflectional suffixes. ~~str~~ |
+| `norm` | The token's norm, i.e. a normalized form of the token text. Can be set in the language's [tokenizer exceptions](/usage/linguistic-features#language-data). ~~int~~ |
+| `norm_` | The token's norm, i.e. a normalized form of the token text. Can be set in the language's [tokenizer exceptions](/usage/linguistic-features#language-data). ~~str~~ |
+| `lower` | Lowercase form of the token. ~~int~~ |
+| `lower_` | Lowercase form of the token text. Equivalent to `Token.text.lower()`. ~~str~~ |
+| `shape` | Transform of the token's string to show orthographic features. Alphabetic characters are replaced by `x` or `X`, and numeric characters are replaced by `d`, and sequences of the same character are truncated after length 4. For example,`"Xxxx"`or`"dd"`. ~~int~~ |
+| `shape_` | Transform of the token's string to show orthographic features. Alphabetic characters are replaced by `x` or `X`, and numeric characters are replaced by `d`, and sequences of the same character are truncated after length 4. For example,`"Xxxx"`or`"dd"`. ~~str~~ |
+| `prefix` | Hash value of a length-N substring from the start of the token. Defaults to `N=1`. ~~int~~ |
+| `prefix_` | A length-N substring from the start of the token. Defaults to `N=1`. ~~str~~ |
+| `suffix` | Hash value of a length-N substring from the end of the token. Defaults to `N=3`. ~~int~~ |
+| `suffix_` | Length-N substring from the end of the token. Defaults to `N=3`. ~~str~~ |
+| `is_alpha` | Does the token consist of alphabetic characters? Equivalent to `token.text.isalpha()`. ~~bool~~ |
+| `is_ascii` | Does the token consist of ASCII characters? Equivalent to `all(ord(c) < 128 for c in token.text)`. ~~bool~~ |
+| `is_digit` | Does the token consist of digits? Equivalent to `token.text.isdigit()`. ~~bool~~ |
+| `is_lower` | Is the token in lowercase? Equivalent to `token.text.islower()`. ~~bool~~ |
+| `is_upper` | Is the token in uppercase? Equivalent to `token.text.isupper()`. ~~bool~~ |
+| `is_title` | Is the token in titlecase? Equivalent to `token.text.istitle()`. ~~bool~~ |
+| `is_punct` | Is the token punctuation? ~~bool~~ |
+| `is_left_punct` | Is the token a left punctuation mark, e.g. `"("` ? ~~bool~~ |
+| `is_right_punct` | Is the token a right punctuation mark, e.g. `")"` ? ~~bool~~ |
+| `is_sent_start` | Does the token start a sentence? ~~bool~~ or `None` if unknown. Defaults to `True` for the first token in the `Doc`. |
+| `is_sent_end` | Does the token end a sentence? ~~bool~~ or `None` if unknown. |
+| `is_space` | Does the token consist of whitespace characters? Equivalent to `token.text.isspace()`. ~~bool~~ |
+| `is_bracket` | Is the token a bracket? ~~bool~~ |
+| `is_quote` | Is the token a quotation mark? ~~bool~~ |
+| `is_currency` | Is the token a currency symbol? ~~bool~~ |
+| `like_url` | Does the token resemble a URL? ~~bool~~ |
+| `like_num` | Does the token represent a number? e.g. "10.9", "10", "ten", etc. ~~bool~~ |
+| `like_email` | Does the token resemble an email address? ~~bool~~ |
+| `is_oov` | Is the token out-of-vocabulary (i.e. does it not have a word vector)? ~~bool~~ |
+| `is_stop` | Is the token part of a "stop list"? ~~bool~~ |
+| `pos` | Coarse-grained part-of-speech from the [Universal POS tag set](https://universaldependencies.org/u/pos/). ~~int~~ |
+| `pos_` | Coarse-grained part-of-speech from the [Universal POS tag set](https://universaldependencies.org/u/pos/). ~~str~~ |
+| `tag` | Fine-grained part-of-speech. ~~int~~ |
+| `tag_` | Fine-grained part-of-speech. ~~str~~ |
+| `morph` 3 | Morphological analysis. ~~MorphAnalysis~~ |
+| `dep` | Syntactic dependency relation. ~~int~~ |
+| `dep_` | Syntactic dependency relation. ~~str~~ |
+| `lang` | Language of the parent document's vocabulary. ~~int~~ |
+| `lang_` | Language of the parent document's vocabulary. ~~str~~ |
+| `prob` | Smoothed log probability estimate of token's word type (context-independent entry in the vocabulary). ~~float~~ |
+| `idx` | The character offset of the token within the parent document. ~~int~~ |
+| `sentiment` | A scalar value indicating the positivity or negativity of the token. ~~float~~ |
+| `lex_id` | Sequential ID of the token's lexical type, used to index into tables, e.g. for word vectors. ~~int~~ |
+| `rank` | Sequential ID of the token's lexical type, used to index into tables, e.g. for word vectors. ~~int~~ |
+| `cluster` | Brown cluster ID. ~~int~~ |
+| `_` | User space for adding custom [attribute extensions](/usage/processing-pipelines#custom-components-attributes). ~~Underscore~~ |
diff --git a/website/docs/api/tokenizer.md b/website/docs/api/tokenizer.mdx
similarity index 81%
rename from website/docs/api/tokenizer.md
rename to website/docs/api/tokenizer.mdx
index 8809c10bc..0a579ab4c 100644
--- a/website/docs/api/tokenizer.md
+++ b/website/docs/api/tokenizer.mdx
@@ -20,7 +20,7 @@ The tokenizer is typically created automatically when a
like punctuation and special case rules from the
[`Language.Defaults`](/api/language#defaults) provided by the language subclass.
-## Tokenizer.\_\_init\_\_ {#init tag="method"}
+## Tokenizer.\_\_init\_\_ {id="init",tag="method"}
Create a `Tokenizer` to create `Doc` objects given unicode text. For examples of
how to construct a custom tokenizer with different tokenization rules, see the
@@ -44,17 +44,18 @@ how to construct a custom tokenizer with different tokenization rules, see the
> tokenizer = nlp.tokenizer
> ```
-| Name | Description |
-| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `vocab` | A storage container for lexical types. ~~Vocab~~ |
-| `rules` | Exceptions and special-cases for the tokenizer. ~~Optional[Dict[str, List[Dict[int, str]]]]~~ |
-| `prefix_search` | A function matching the signature of `re.compile(string).search` to match prefixes. ~~Optional[Callable[[str], Optional[Match]]]~~ |
-| `suffix_search` | A function matching the signature of `re.compile(string).search` to match suffixes. ~~Optional[Callable[[str], Optional[Match]]]~~ |
-| `infix_finditer` | A function matching the signature of `re.compile(string).finditer` to find infixes. ~~Optional[Callable[[str], Iterator[Match]]]~~ |
-| `token_match` | A function matching the signature of `re.compile(string).match` to find token matches. ~~Optional[Callable[[str], Optional[Match]]]~~ |
-| `url_match` | A function matching the signature of `re.compile(string).match` to find token matches after considering prefixes and suffixes. ~~Optional[Callable[[str], Optional[Match]]]~~ |
+| Name | Description |
+| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `vocab` | A storage container for lexical types. ~~Vocab~~ |
+| `rules` | Exceptions and special-cases for the tokenizer. ~~Optional[Dict[str, List[Dict[int, str]]]]~~ |
+| `prefix_search` | A function matching the signature of `re.compile(string).search` to match prefixes. ~~Optional[Callable[[str], Optional[Match]]]~~ |
+| `suffix_search` | A function matching the signature of `re.compile(string).search` to match suffixes. ~~Optional[Callable[[str], Optional[Match]]]~~ |
+| `infix_finditer` | A function matching the signature of `re.compile(string).finditer` to find infixes. ~~Optional[Callable[[str], Iterator[Match]]]~~ |
+| `token_match` | A function matching the signature of `re.compile(string).match` to find token matches. ~~Optional[Callable[[str], Optional[Match]]]~~ |
+| `url_match` | A function matching the signature of `re.compile(string).match` to find token matches after considering prefixes and suffixes. ~~Optional[Callable[[str], Optional[Match]]]~~ |
+| `faster_heuristics` 3.3.0 | Whether to restrict the final `Matcher`-based pass for rules to those containing affixes or space. Defaults to `True`. ~~bool~~ |
-## Tokenizer.\_\_call\_\_ {#call tag="method"}
+## Tokenizer.\_\_call\_\_ {id="call",tag="method"}
Tokenize a string.
@@ -70,7 +71,7 @@ Tokenize a string.
| `string` | The string to tokenize. ~~str~~ |
| **RETURNS** | A container for linguistic annotations. ~~Doc~~ |
-## Tokenizer.pipe {#pipe tag="method"}
+## Tokenizer.pipe {id="pipe",tag="method"}
Tokenize a stream of texts.
@@ -88,7 +89,7 @@ Tokenize a stream of texts.
| `batch_size` | The number of texts to accumulate in an internal buffer. Defaults to `1000`. ~~int~~ |
| **YIELDS** | The tokenized `Doc` objects, in order. ~~Doc~~ |
-## Tokenizer.find_infix {#find_infix tag="method"}
+## Tokenizer.find_infix {id="find_infix",tag="method"}
Find internal split points of the string.
@@ -97,7 +98,7 @@ Find internal split points of the string.
| `string` | The string to split. ~~str~~ |
| **RETURNS** | A list of `re.MatchObject` objects that have `.start()` and `.end()` methods, denoting the placement of internal segment separators, e.g. hyphens. ~~List[Match]~~ |
-## Tokenizer.find_prefix {#find_prefix tag="method"}
+## Tokenizer.find_prefix {id="find_prefix",tag="method"}
Find the length of a prefix that should be segmented from the string, or `None`
if no prefix rules match.
@@ -107,7 +108,7 @@ if no prefix rules match.
| `string` | The string to segment. ~~str~~ |
| **RETURNS** | The length of the prefix if present, otherwise `None`. ~~Optional[int]~~ |
-## Tokenizer.find_suffix {#find_suffix tag="method"}
+## Tokenizer.find_suffix {id="find_suffix",tag="method"}
Find the length of a suffix that should be segmented from the string, or `None`
if no suffix rules match.
@@ -117,7 +118,7 @@ if no suffix rules match.
| `string` | The string to segment. ~~str~~ |
| **RETURNS** | The length of the suffix if present, otherwise `None`. ~~Optional[int]~~ |
-## Tokenizer.add_special_case {#add_special_case tag="method"}
+## Tokenizer.add_special_case {id="add_special_case",tag="method"}
Add a special-case tokenization rule. This mechanism is also used to add custom
tokenizer exceptions to the language data. See the usage guide on the
@@ -138,7 +139,7 @@ details and examples.
| `string` | The string to specially tokenize. ~~str~~ |
| `token_attrs` | A sequence of dicts, where each dict describes a token and its attributes. The `ORTH` fields of the attributes must exactly match the string when they are concatenated. ~~Iterable[Dict[int, str]]~~ |
-## Tokenizer.explain {#explain tag="method"}
+## Tokenizer.explain {id="explain",tag="method"}
Tokenize a string with a slow debugging tokenizer that provides information
about which tokenizer rule or pattern was matched for each token. The tokens
@@ -157,7 +158,7 @@ produced are identical to `Tokenizer.__call__` except for whitespace tokens.
| `string` | The string to tokenize with the debugging tokenizer. ~~str~~ |
| **RETURNS** | A list of `(pattern_string, token_string)` tuples. ~~List[Tuple[str, str]]~~ |
-## Tokenizer.to_disk {#to_disk tag="method"}
+## Tokenizer.to_disk {id="to_disk",tag="method"}
Serialize the tokenizer to disk.
@@ -174,7 +175,7 @@ Serialize the tokenizer to disk.
| _keyword-only_ | |
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
-## Tokenizer.from_disk {#from_disk tag="method"}
+## Tokenizer.from_disk {id="from_disk",tag="method"}
Load the tokenizer from disk. Modifies the object in place and returns it.
@@ -192,7 +193,7 @@ Load the tokenizer from disk. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The modified `Tokenizer` object. ~~Tokenizer~~ |
-## Tokenizer.to_bytes {#to_bytes tag="method"}
+## Tokenizer.to_bytes {id="to_bytes",tag="method"}
> #### Example
>
@@ -209,7 +210,7 @@ Serialize the tokenizer to a bytestring.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The serialized form of the `Tokenizer` object. ~~bytes~~ |
-## Tokenizer.from_bytes {#from_bytes tag="method"}
+## Tokenizer.from_bytes {id="from_bytes",tag="method"}
Load the tokenizer from a bytestring. Modifies the object in place and returns
it.
@@ -229,7 +230,7 @@ it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The `Tokenizer` object. ~~Tokenizer~~ |
-## Attributes {#attributes}
+## Attributes {id="attributes"}
| Name | Description |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -240,7 +241,7 @@ it.
| `token_match` | A function matching the signature of `re.compile(string).match` to find token matches. Returns an `re.MatchObject` or `None`. ~~Optional[Callable[[str], Optional[Match]]]~~ |
| `rules` | A dictionary of tokenizer exceptions and special cases. ~~Optional[Dict[str, List[Dict[int, str]]]]~~ |
-## Serialization fields {#serialization-fields}
+## Serialization fields {id="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
diff --git a/website/docs/api/top-level.md b/website/docs/api/top-level.mdx
similarity index 67%
rename from website/docs/api/top-level.md
rename to website/docs/api/top-level.mdx
index 1a3e9da46..9748719d7 100644
--- a/website/docs/api/top-level.md
+++ b/website/docs/api/top-level.mdx
@@ -13,9 +13,9 @@ menu:
- ['Utility Functions', 'util']
---
-## spaCy {#spacy hidden="true"}
+## spaCy {id="spacy",hidden="true"}
-### spacy.load {#spacy.load tag="function"}
+### spacy.load {id="spacy.load",tag="function"}
Load a pipeline using the name of an installed
[package](/usage/saving-loading#models), a string path or a `Path`-like object.
@@ -45,23 +45,23 @@ specified separately using the new `exclude` keyword argument.
> nlp = spacy.load("en_core_web_sm", exclude=["parser", "tagger"])
> ```
-| Name | Description |
-| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `name` | Pipeline to load, i.e. package name or path. ~~Union[str, Path]~~ |
-| _keyword-only_ | |
-| `vocab` | Optional shared vocab to pass in on initialization. If `True` (default), a new `Vocab` object will be created. ~~Union[Vocab, bool]~~ |
-| `disable` | Names of pipeline components to [disable](/usage/processing-pipelines#disabling). Disabled pipes will be loaded but they won't be run unless you explicitly enable them by calling [nlp.enable_pipe](/api/language#enable_pipe). ~~List[str]~~ |
-| `exclude` 3 | Names of pipeline components to [exclude](/usage/processing-pipelines#disabling). Excluded components won't be loaded. ~~List[str]~~ |
-| `config` 3 | Optional config overrides, either as nested dict or dict keyed by section value in dot notation, e.g. `"components.name.value"`. ~~Union[Dict[str, Any], Config]~~ |
-| **RETURNS** | A `Language` object with the loaded pipeline. ~~Language~~ |
+| Name | Description |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `name` | Pipeline to load, i.e. package name or path. ~~Union[str, Path]~~ |
+| _keyword-only_ | |
+| `vocab` | Optional shared vocab to pass in on initialization. If `True` (default), a new `Vocab` object will be created. ~~Union[Vocab, bool]~~ |
+| `disable` | Name(s) of pipeline component(s) to [disable](/usage/processing-pipelines#disabling). Disabled pipes will be loaded but they won't be run unless you explicitly enable them by calling [nlp.enable_pipe](/api/language#enable_pipe). Is merged with the config entry `nlp.disabled`. ~~Union[str, Iterable[str]]~~ |
+| `enable` 3.4 | Name(s) of pipeline component(s) to [enable](/usage/processing-pipelines#disabling). All other pipes will be disabled. ~~Union[str, Iterable[str]]~~ |
+| `exclude` 3 | Name(s) of pipeline component(s) to [exclude](/usage/processing-pipelines#disabling). Excluded components won't be loaded. ~~Union[str, Iterable[str]]~~ |
+| `config` 3 | Optional config overrides, either as nested dict or dict keyed by section value in dot notation, e.g. `"components.name.value"`. ~~Union[Dict[str, Any], Config]~~ |
+| **RETURNS** | A `Language` object with the loaded pipeline. ~~Language~~ |
Essentially, `spacy.load()` is a convenience wrapper that reads the pipeline's
[`config.cfg`](/api/data-formats#config), uses the language and pipeline
information to construct a `Language` object, loads in the model data and
weights, and returns it.
-```python
-### Abstract example
+```python {title="Abstract example"}
cls = spacy.util.get_lang_class(lang) # 1. Get Language class, e.g. English
nlp = cls() # 2. Initialize it
for name in pipeline:
@@ -69,7 +69,7 @@ for name in pipeline:
nlp.from_disk(data_path) # 4. Load in the binary data
```
-### spacy.blank {#spacy.blank tag="function" new="2"}
+### spacy.blank {id="spacy.blank",tag="function",version="2"}
Create a blank pipeline of a given language class. This function is the twin of
`spacy.load()`.
@@ -90,7 +90,7 @@ Create a blank pipeline of a given language class. This function is the twin of
| `meta` | Optional meta overrides for [`nlp.meta`](/api/language#meta). ~~Dict[str, Any]~~ |
| **RETURNS** | An empty `Language` object of the appropriate subclass. ~~Language~~ |
-### spacy.info {#spacy.info tag="function"}
+### spacy.info {id="spacy.info",tag="function"}
The same as the [`info` command](/api/cli#info). Pretty-print information about
your installation, installed pipelines and local setup from within spaCy.
@@ -110,7 +110,7 @@ your installation, installed pipelines and local setup from within spaCy.
| `markdown` | Print information as Markdown. ~~bool~~ |
| `silent` | Don't print anything, just return. ~~bool~~ |
-### spacy.explain {#spacy.explain tag="function"}
+### spacy.explain {id="spacy.explain",tag="function"}
Get a description for a given POS tag, dependency label or entity type. For a
list of available terms, see [`glossary.py`](%%GITHUB_SPACY/spacy/glossary.py).
@@ -133,7 +133,7 @@ list of available terms, see [`glossary.py`](%%GITHUB_SPACY/spacy/glossary.py).
| `term` | Term to explain. ~~str~~ |
| **RETURNS** | The explanation, or `None` if not found in the glossary. ~~Optional[str]~~ |
-### spacy.prefer_gpu {#spacy.prefer_gpu tag="function" new="2.0.14"}
+### spacy.prefer_gpu {id="spacy.prefer_gpu",tag="function",version="2.0.14"}
Allocate data and perform operations on [GPU](/usage/#gpu), if available. If
data has already been allocated on CPU, it will not be moved. Ideally, this
@@ -161,7 +161,7 @@ ensure that the model is loaded on the correct device. See
| `gpu_id` | Device index to select. Defaults to `0`. ~~int~~ |
| **RETURNS** | Whether the GPU was activated. ~~bool~~ |
-### spacy.require_gpu {#spacy.require_gpu tag="function" new="2.0.14"}
+### spacy.require_gpu {id="spacy.require_gpu",tag="function",version="2.0.14"}
Allocate data and perform operations on [GPU](/usage/#gpu). Will raise an error
if no GPU is available. If data has already been allocated on CPU, it will not
@@ -189,7 +189,7 @@ ensure that the model is loaded on the correct device. See
| `gpu_id` | Device index to select. Defaults to `0`. ~~int~~ |
| **RETURNS** | `True` ~~bool~~ |
-### spacy.require_cpu {#spacy.require_cpu tag="function" new="3.0.0"}
+### spacy.require_cpu {id="spacy.require_cpu",tag="function",version="3.0.0"}
Allocate data and perform operations on CPU. If data has already been allocated
on GPU, it will not be moved. Ideally, this function should be called right
@@ -215,12 +215,12 @@ ensure that the model is loaded on the correct device. See
| ----------- | --------------- |
| **RETURNS** | `True` ~~bool~~ |
-## displaCy {#displacy source="spacy/displacy"}
+## displaCy {id="displacy",source="spacy/displacy"}
As of v2.0, spaCy comes with a built-in visualization suite. For more info and
examples, see the usage guide on [visualizing spaCy](/usage/visualizers).
-### displacy.serve {#displacy.serve tag="method" new="2"}
+### displacy.serve {id="displacy.serve",tag="method",version="2"}
Serve a dependency parse tree or named entity visualization to view it in your
browser. Will run a simple web server.
@@ -236,18 +236,19 @@ browser. Will run a simple web server.
> displacy.serve([doc1, doc2], style="dep")
> ```
-| Name | Description |
-| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `docs` | Document(s) or span(s) to visualize. ~~Union[Iterable[Union[Doc, Span]], Doc, Span]~~ |
-| `style` | Visualization style, `"dep"` or `"ent"`. Defaults to `"dep"`. ~~str~~ |
-| `page` | Render markup as full HTML page. Defaults to `True`. ~~bool~~ |
-| `minify` | Minify HTML markup. Defaults to `False`. ~~bool~~ |
-| `options` | [Visualizer-specific options](#displacy_options), e.g. colors. ~~Dict[str, Any]~~ |
-| `manual` | Don't parse `Doc` and instead expect a dict or list of dicts. [See here](/usage/visualizers#manual-usage) for formats and examples. Defaults to `False`. ~~bool~~ |
-| `port` | Port to serve visualization. Defaults to `5000`. ~~int~~ |
-| `host` | Host to serve visualization. Defaults to `"0.0.0.0"`. ~~str~~ |
+| Name | Description |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `docs` | Document(s) or span(s) to visualize. ~~Union[Iterable[Union[Doc, Span]], Doc, Span]~~ |
+| `style` 3.3 | Visualization style, `"dep"`, `"ent"` or `"span"`. Defaults to `"dep"`. ~~str~~ |
+| `page` | Render markup as full HTML page. Defaults to `True`. ~~bool~~ |
+| `minify` | Minify HTML markup. Defaults to `False`. ~~bool~~ |
+| `options` | [Visualizer-specific options](#displacy_options), e.g. colors. ~~Dict[str, Any]~~ |
+| `manual` | Don't parse `Doc` and instead expect a dict or list of dicts. [See here](/usage/visualizers#manual-usage) for formats and examples. Defaults to `False`. ~~bool~~ |
+| `port` | Port to serve visualization. Defaults to `5000`. ~~int~~ |
+| `host` | Host to serve visualization. Defaults to `"0.0.0.0"`. ~~str~~ |
+| `auto_select_port` 3.5 | If `True`, automatically switch to a different port if the specified port is already in use. Defaults to `False`. ~~bool~~ |
-### displacy.render {#displacy.render tag="method" new="2"}
+### displacy.render {id="displacy.render",tag="method",version="2"}
Render a dependency parse tree or named entity visualization.
@@ -263,21 +264,88 @@ Render a dependency parse tree or named entity visualization.
| Name | Description |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `docs` | Document(s) or span(s) to visualize. ~~Union[Iterable[Union[Doc, Span]], Doc, Span]~~ |
-| `style` | Visualization style, `"dep"` or `"ent"`. Defaults to `"dep"`. ~~str~~ |
-| `page` | Render markup as full HTML page. Defaults to `True`. ~~bool~~ |
+| `docs` | Document(s) or span(s) to visualize. ~~Union[Iterable[Union[Doc, Span, dict]], Doc, Span, dict]~~ |
+| `style` | Visualization style, `"dep"`, `"ent"` or `"span"` 3.3. Defaults to `"dep"`. ~~str~~ |
+| `page` | Render markup as full HTML page. Defaults to `False`. ~~bool~~ |
| `minify` | Minify HTML markup. Defaults to `False`. ~~bool~~ |
| `options` | [Visualizer-specific options](#displacy_options), e.g. colors. ~~Dict[str, Any]~~ |
| `manual` | Don't parse `Doc` and instead expect a dict or list of dicts. [See here](/usage/visualizers#manual-usage) for formats and examples. Defaults to `False`. ~~bool~~ |
| `jupyter` | Explicitly enable or disable "[Jupyter](http://jupyter.org/) mode" to return markup ready to be rendered in a notebook. Detected automatically if `None` (default). ~~Optional[bool]~~ |
| **RETURNS** | The rendered HTML markup. ~~str~~ |
-### Visualizer options {#displacy_options}
+### displacy.parse_deps {id="displacy.parse_deps",tag="method",version="2"}
+
+Generate dependency parse in `{'words': [], 'arcs': []}` format. For use with
+the `manual=True` argument in `displacy.render`.
+
+> #### Example
+>
+> ```python
+> import spacy
+> from spacy import displacy
+> nlp = spacy.load("en_core_web_sm")
+> doc = nlp("This is a sentence.")
+> deps_parse = displacy.parse_deps(doc)
+> html = displacy.render(deps_parse, style="dep", manual=True)
+> ```
+
+| Name | Description |
+| ----------- | ------------------------------------------------------------------- |
+| `orig_doc` | Doc to parse dependencies. ~~Doc~~ |
+| `options` | Dependency parse specific visualisation options. ~~Dict[str, Any]~~ |
+| **RETURNS** | Generated dependency parse keyed by words and arcs. ~~dict~~ |
+
+### displacy.parse_ents {id="displacy.parse_ents",tag="method",version="2"}
+
+Generate named entities in `[{start: i, end: i, label: 'label'}]` format. For
+use with the `manual=True` argument in `displacy.render`.
+
+> #### Example
+>
+> ```python
+> import spacy
+> from spacy import displacy
+> nlp = spacy.load("en_core_web_sm")
+> doc = nlp("But Google is starting from behind.")
+> ents_parse = displacy.parse_ents(doc)
+> html = displacy.render(ents_parse, style="ent", manual=True)
+> ```
+
+| Name | Description |
+| ----------- | ------------------------------------------------------------------- |
+| `doc` | Doc to parse entities. ~~Doc~~ |
+| `options` | NER-specific visualisation options. ~~Dict[str, Any]~~ |
+| **RETURNS** | Generated entities keyed by text (original text) and ents. ~~dict~~ |
+
+### displacy.parse_spans {id="displacy.parse_spans",tag="method",version="2"}
+
+Generate spans in `[{start_token: i, end_token: i, label: 'label'}]` format. For
+use with the `manual=True` argument in `displacy.render`.
+
+> #### Example
+>
+> ```python
+> import spacy
+> from spacy import displacy
+> nlp = spacy.load("en_core_web_sm")
+> doc = nlp("But Google is starting from behind.")
+> doc.spans['orgs'] = [doc[1:2]]
+> ents_parse = displacy.parse_spans(doc, options={"spans_key" : "orgs"})
+> html = displacy.render(ents_parse, style="span", manual=True)
+> ```
+
+| Name | Description |
+| ----------- | ------------------------------------------------------------------- |
+| `doc` | Doc to parse entities. ~~Doc~~ |
+| `options` | Span-specific visualisation options. ~~Dict[str, Any]~~ |
+| **RETURNS** | Generated entities keyed by text (original text) and ents. ~~dict~~ |
+
+### Visualizer options {id="displacy_options"}
The `options` argument lets you specify additional settings for each visualizer.
If a setting is not present in the options, the default value will be used.
-#### Dependency Visualizer options {#options-dep}
+#### Dependency Visualizer options {id="options-dep"}
> #### Example
>
@@ -286,24 +354,24 @@ If a setting is not present in the options, the default value will be used.
> displacy.serve(doc, style="dep", options=options)
> ```
-| Name | Description |
-| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `fine_grained` | Use fine-grained part-of-speech tags (`Token.tag_`) instead of coarse-grained tags (`Token.pos_`). Defaults to `False`. ~~bool~~ |
-| `add_lemma` 2.2.4 | Print the lemmas in a separate row below the token texts. Defaults to `False`. ~~bool~~ |
-| `collapse_punct` | Attach punctuation to tokens. Can make the parse more readable, as it prevents long arcs to attach punctuation. Defaults to `True`. ~~bool~~ |
-| `collapse_phrases` | Merge noun phrases into one token. Defaults to `False`. ~~bool~~ |
-| `compact` | "Compact mode" with square arrows that takes up less space. Defaults to `False`. ~~bool~~ |
-| `color` | Text color (HEX, RGB or color names). Defaults to `"#000000"`. ~~str~~ |
-| `bg` | Background color (HEX, RGB or color names). Defaults to `"#ffffff"`. ~~str~~ |
-| `font` | Font name or font family for all text. Defaults to `"Arial"`. ~~str~~ |
-| `offset_x` | Spacing on left side of the SVG in px. Defaults to `50`. ~~int~~ |
-| `arrow_stroke` | Width of arrow path in px. Defaults to `2`. ~~int~~ |
-| `arrow_width` | Width of arrow head in px. Defaults to `10` in regular mode and `8` in compact mode. ~~int~~ |
-| `arrow_spacing` | Spacing between arrows in px to avoid overlaps. Defaults to `20` in regular mode and `12` in compact mode. ~~int~~ |
-| `word_spacing` | Vertical spacing between words and arcs in px. Defaults to `45`. ~~int~~ |
-| `distance` | Distance between words in px. Defaults to `175` in regular mode and `150` in compact mode. ~~int~~ |
+| Name | Description |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fine_grained` | Use fine-grained part-of-speech tags (`Token.tag_`) instead of coarse-grained tags (`Token.pos_`). Defaults to `False`. ~~bool~~ |
+| `add_lemma` | Print the lemmas in a separate row below the token texts. Defaults to `False`. ~~bool~~ |
+| `collapse_punct` | Attach punctuation to tokens. Can make the parse more readable, as it prevents long arcs to attach punctuation. Defaults to `True`. ~~bool~~ |
+| `collapse_phrases` | Merge noun phrases into one token. Defaults to `False`. ~~bool~~ |
+| `compact` | "Compact mode" with square arrows that takes up less space. Defaults to `False`. ~~bool~~ |
+| `color` | Text color (HEX, RGB or color names). Defaults to `"#000000"`. ~~str~~ |
+| `bg` | Background color (HEX, RGB or color names). Defaults to `"#ffffff"`. ~~str~~ |
+| `font` | Font name or font family for all text. Defaults to `"Arial"`. ~~str~~ |
+| `offset_x` | Spacing on left side of the SVG in px. Defaults to `50`. ~~int~~ |
+| `arrow_stroke` | Width of arrow path in px. Defaults to `2`. ~~int~~ |
+| `arrow_width` | Width of arrow head in px. Defaults to `10` in regular mode and `8` in compact mode. ~~int~~ |
+| `arrow_spacing` | Spacing between arrows in px to avoid overlaps. Defaults to `20` in regular mode and `12` in compact mode. ~~int~~ |
+| `word_spacing` | Vertical spacing between words and arcs in px. Defaults to `45`. ~~int~~ |
+| `distance` | Distance between words in px. Defaults to `175` in regular mode and `150` in compact mode. ~~int~~ |
-#### Named Entity Visualizer options {#displacy_options-ent}
+#### Named Entity Visualizer options {id="displacy_options-ent"}
> #### Example
>
@@ -317,13 +385,29 @@ If a setting is not present in the options, the default value will be used.
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ents` | Entity types to highlight or `None` for all types (default). ~~Optional[List[str]]~~ |
| `colors` | Color overrides. Entity types should be mapped to color names or values. ~~Dict[str, str]~~ |
-| `template` 2.2 | Optional template to overwrite the HTML used to render entity spans. Should be a format string and can use `{bg}`, `{text}` and `{label}`. See [`templates.py`](%%GITHUB_SPACY/spacy/displacy/templates.py) for examples. ~~Optional[str]~~ |
+| `template` | Optional template to overwrite the HTML used to render entity spans. Should be a format string and can use `{bg}`, `{text}` and `{label}`. See [`templates.py`](%%GITHUB_SPACY/spacy/displacy/templates.py) for examples. ~~Optional[str]~~ |
| `kb_url_template` 3.2.1 | Optional template to construct the KB url for the entity to link to. Expects a python f-string format with single field to fill in. ~~Optional[str]~~ |
+#### Span Visualizer options {id="displacy_options-span"}
+
+> #### Example
+>
+> ```python
+> options = {"spans_key": "sc"}
+> displacy.serve(doc, style="span", options=options)
+> ```
+
+| Name | Description |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `spans_key` | Which spans key to render spans from. Default is `"sc"`. ~~str~~ |
+| `templates` | Dictionary containing the keys `"span"`, `"slice"`, and `"start"`. These dictate how the overall span, a span slice, and the starting token will be rendered. ~~Optional[Dict[str, str]~~ |
+| `kb_url_template` | Optional template to construct the KB url for the entity to link to. Expects a python f-string format with single field to fill in ~~Optional[str]~~ |
+| `colors` | Color overrides. Entity types should be mapped to color names or values. ~~Dict[str, str]~~ |
+
By default, displaCy comes with colors for all entity types used by
-[spaCy's trained pipelines](/models). If you're using custom entity types, you
-can use the `colors` setting to add your own colors for them. Your application
-or pipeline package can also expose a
+[spaCy's trained pipelines](/models) for both entity and span visualizer. If
+you're using custom entity types, you can use the `colors` setting to add your
+own colors for them. Your application or pipeline package can also expose a
[`spacy_displacy_colors` entry point](/usage/saving-loading#entry-points-displacy)
to add custom labels and their colors automatically.
@@ -335,7 +419,7 @@ span. If you wish to link an entity to their URL then consider using the
should redirect you to their Wikidata page, in this case
`https://www.wikidata.org/wiki/Q95`.
-## registry {#registry source="spacy/util.py" new="3"}
+## registry {id="registry",source="spacy/util.py",version="3"}
spaCy's function registry extends
[Thinc's `registry`](https://thinc.ai/docs/api-config#registry) and allows you
@@ -367,7 +451,7 @@ factories.
| Registry name | Description |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `architectures` | Registry for functions that create [model architectures](/api/architectures). Can be used to register custom model architectures and reference them in the `config.cfg`. |
-| `augmenters` | Registry for functions that create [data augmentation](#augmenters) callbacks for corpora and other training data iterators. |
+| `augmenters` | Registry for functions that create [data augmentation](#augmenters) callbacks for corpora and other training data iterators. |
| `batchers` | Registry for training and evaluation [data batchers](#batchers). |
| `callbacks` | Registry for custom callbacks to [modify the `nlp` object](/usage/training#custom-code-nlp-callbacks) before training. |
| `displacy_colors` | Registry for custom color scheme for the [`displacy` NER visualizer](/usage/visualizers). Automatically reads from [entry points](/usage/saving-loading#entry-points). |
@@ -385,7 +469,7 @@ factories.
| `scorers` | Registry for functions that create scoring methods for user with the [`Scorer`](/api/scorer). Scoring methods are called with `Iterable[Example]` and arbitrary `\*\*kwargs` and return scores as `Dict[str, Any]`. |
| `tokenizers` | Registry for tokenizer factories. Registered functions should return a callback that receives the `nlp` object and returns a [`Tokenizer`](/api/tokenizer) or a custom callable. |
-### spacy-transformers registry {#registry-transformers}
+### spacy-transformers registry {id="registry-transformers"}
The following registries are added by the
[`spacy-transformers`](https://github.com/explosion/spacy-transformers) package.
@@ -410,7 +494,7 @@ See the [`Transformer`](/api/transformer) API reference and
| [`span_getters`](/api/transformer#span_getters) | Registry for functions that take a batch of `Doc` objects and return a list of `Span` objects to process by the transformer, e.g. sentences. |
| [`annotation_setters`](/api/transformer#annotation_setters) | Registry for functions that create annotation setters. Annotation setters are functions that take a batch of `Doc` objects and a [`FullTransformerBatch`](/api/transformer#fulltransformerbatch) and can set additional annotations on the `Doc`. |
-## Loggers {#loggers source="spacy/training/loggers.py" new="3"}
+## Loggers {id="loggers",source="spacy/training/loggers.py",version="3"}
A logger records the training results. When a logger is created, two functions
are returned: one for logging the information for each training step, and a
@@ -421,28 +505,32 @@ finished. To log each training step, a
and the accuracy scores on the development set.
The built-in, default logger is the ConsoleLogger, which prints results to the
-console in tabular format. The
+console in tabular format and saves them to a `jsonl` file. The
[spacy-loggers](https://github.com/explosion/spacy-loggers) package, included as
-a dependency of spaCy, enables other loggers, such as one that
-sends results to a [Weights & Biases](https://www.wandb.com/) dashboard.
+a dependency of spaCy, enables other loggers, such as one that sends results to
+a [Weights & Biases](https://www.wandb.com/) dashboard.
Instead of using one of the built-in loggers, you can
[implement your own](/usage/training#custom-logging).
-#### spacy.ConsoleLogger.v1 {#ConsoleLogger tag="registered function"}
+#### spacy.ConsoleLogger.v2 {tag="registered function"}
> #### Example config
>
> ```ini
> [training.logger]
-> @loggers = "spacy.ConsoleLogger.v1"
+> @loggers = "spacy.ConsoleLogger.v2"
+> progress_bar = true
+> console_output = true
+> output_file = "training_log.jsonl"
> ```
-Writes the results of a training step to the console in a tabular format.
+Writes the results of a training step to the console in a tabular format and
+saves them to a `jsonl` file.
-```cli
+```bash
$ python -m spacy train config.cfg
```
@@ -452,22 +540,23 @@ $ python -m spacy train config.cfg
ℹ Pipeline: ['tok2vec', 'tagger']
ℹ Start training
ℹ Training. Initial learn rate: 0.0
+ℹ Saving results to training_log.jsonl
E # LOSS TOK2VEC LOSS TAGGER TAG_ACC SCORE
--- ------ ------------ ----------- ------- ------
- 1 0 0.00 86.20 0.22 0.00
- 1 200 3.08 18968.78 34.00 0.34
- 1 400 31.81 22539.06 33.64 0.34
- 1 600 92.13 22794.91 43.80 0.44
- 1 800 183.62 21541.39 56.05 0.56
- 1 1000 352.49 25461.82 65.15 0.65
- 1 1200 422.87 23708.82 71.84 0.72
- 1 1400 601.92 24994.79 76.57 0.77
- 1 1600 662.57 22268.02 80.20 0.80
- 1 1800 1101.50 28413.77 82.56 0.83
- 1 2000 1253.43 28736.36 85.00 0.85
- 1 2200 1411.02 28237.53 87.42 0.87
- 1 2400 1605.35 28439.95 88.70 0.89
+ 0 0 0.00 86.20 0.22 0.00
+ 0 200 3.08 18968.78 34.00 0.34
+ 0 400 31.81 22539.06 33.64 0.34
+ 0 600 92.13 22794.91 43.80 0.44
+ 0 800 183.62 21541.39 56.05 0.56
+ 0 1000 352.49 25461.82 65.15 0.65
+ 0 1200 422.87 23708.82 71.84 0.72
+ 0 1400 601.92 24994.79 76.57 0.77
+ 0 1600 662.57 22268.02 80.20 0.80
+ 0 1800 1101.50 28413.77 82.56 0.83
+ 0 2000 1253.43 28736.36 85.00 0.85
+ 0 2200 1411.02 28237.53 87.42 0.87
+ 0 2400 1605.35 28439.95 88.70 0.89
```
Note that the cumulative loss keeps increasing within one epoch, but should
@@ -475,9 +564,37 @@ start decreasing across epochs.
-## Readers {#readers}
+| Name | Description |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `progress_bar` | Whether the logger should print a progress bar tracking the steps till the next evaluation pass (default: `False`). ~~bool~~ |
+| `console_output` | Whether the logger should print the logs in the console (default: `True`). ~~bool~~ |
+| `output_file` | The file to save the training logs to (default: `None`). ~~Optional[Union[str, Path]]~~ |
-### File readers {#file-readers source="github.com/explosion/srsly" new="3"}
+#### spacy.ConsoleLogger.v3 {id="ConsoleLogger",tag="registered function"}
+
+> #### Example config
+>
+> ```ini
+> [training.logger]
+> @loggers = "spacy.ConsoleLogger.v3"
+> progress_bar = "all_steps"
+> console_output = true
+> output_file = "training_log.jsonl"
+> ```
+
+Writes the results of a training step to the console in a tabular format and
+optionally saves them to a `jsonl` file.
+
+| Name | Description |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `progress_bar` | Type of progress bar to show in the console: `"train"`, `"eval"` or `None`. |
+| | The bar tracks the number of steps until `training.max_steps` and `training.eval_frequency` are reached respectively (default: `None`). ~~Optional[str]~~ |
+| `console_output` | Whether the logger should print the logs in the console (default: `True`). ~~bool~~ |
+| `output_file` | The file to save the training logs to (default: `None`). ~~Optional[Union[str, Path]]~~ |
+
+## Readers {id="readers"}
+
+### File readers {id="file-readers",source="github.com/explosion/srsly",version="3"}
The following file readers are provided by our serialization library
[`srsly`](https://github.com/explosion/srsly). All registered functions take one
@@ -507,7 +624,7 @@ blocks that are **not executed at runtime** – for example, in `[training]` and
-#### spacy.read_labels.v1 {#read_labels tag="registered function"}
+#### spacy.read_labels.v1 {id="read_labels",tag="registered function"}
Read a JSON-formatted labels file generated with
[`init labels`](/api/cli#init-labels). Typically used in the
@@ -533,7 +650,7 @@ label sets.
| `require` | Whether to require the file to exist. If set to `False` and the labels file doesn't exist, the loader will return `None` and the `initialize` method will extract the labels from the data. Defaults to `False`. ~~bool~~ |
| **CREATES** | The list of labels. ~~List[str]~~ |
-### Corpus readers {#corpus-readers source="spacy/training/corpus.py" new="3"}
+### Corpus readers {id="corpus-readers",source="spacy/training/corpus.py",version="3"}
Corpus readers are registered functions that load data and return a function
that takes the current `nlp` object and yields [`Example`](/api/example) objects
@@ -543,7 +660,7 @@ with your own registered function in the
[`@readers` registry](/api/top-level#registry) to customize the data loading and
streaming.
-#### spacy.Corpus.v1 {#corpus tag="registered function"}
+#### spacy.Corpus.v1 {id="corpus",tag="registered function"}
The `Corpus` reader manages annotated corpora and can be used for training and
development datasets in the [DocBin](/api/docbin) (`.spacy`) format. Also see
@@ -563,16 +680,16 @@ the [`Corpus`](/api/corpus) class.
> limit = 0
> ```
-| Name | Description |
-| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `path` | The directory or filename to read from. Expects data in spaCy's binary [`.spacy` format](/api/data-formats#binary-training). ~~Union[str, Path]~~ |
-| `gold_preproc` | Whether to set up the Example object with gold-standard sentences and tokens for the predictions. See [`Corpus`](/api/corpus#init) for details. ~~bool~~ |
-| `max_length` | Maximum document length. Longer documents will be split into sentences, if sentence boundaries are available. Defaults to `0` for no limit. ~~int~~ |
-| `limit` | Limit corpus to a subset of examples, e.g. for debugging. Defaults to `0` for no limit. ~~int~~ |
-| `augmenter` | Apply some simply data augmentation, where we replace tokens with variations. This is especially useful for punctuation and case replacement, to help generalize beyond corpora that don't have smart-quotes, or only have smart quotes, etc. Defaults to `None`. ~~Optional[Callable]~~ |
-| **CREATES** | The corpus reader. ~~Corpus~~ |
+| Name | Description |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `path` | The directory or filename to read from. Expects data in spaCy's binary [`.spacy` format](/api/data-formats#binary-training). ~~Union[str, Path]~~ |
+| `gold_preproc` | Whether to set up the Example object with gold-standard sentences and tokens for the predictions. See [`Corpus`](/api/corpus#init) for details. ~~bool~~ |
+| `max_length` | Maximum document length. Longer documents will be split into sentences, if sentence boundaries are available. Defaults to `0` for no limit. ~~int~~ |
+| `limit` | Limit corpus to a subset of examples, e.g. for debugging. Defaults to `0` for no limit. ~~int~~ |
+| `augmenter` | Apply some simply data augmentation, where we replace tokens with variations. This is especially useful for punctuation and case replacement, to help generalize beyond corpora that don't have smart-quotes, or only have smart quotes, etc. Defaults to `None`. ~~Optional[Callable]~~ |
+| **CREATES** | The corpus reader. ~~Corpus~~ |
-#### spacy.JsonlCorpus.v1 {#jsonlcorpus tag="registered function"}
+#### spacy.JsonlCorpus.v1 {id="jsonlcorpus",tag="registered function"}
Create [`Example`](/api/example) objects from a JSONL (newline-delimited JSON)
file of texts keyed by `"text"`. Can be used to read the raw text corpus for
@@ -601,7 +718,7 @@ JSONL file. Also see the [`JsonlCorpus`](/api/corpus#jsonlcorpus) class.
| `limit` | Limit corpus to a subset of examples, e.g. for debugging. Defaults to `0` for no limit. ~~int~~ |
| **CREATES** | The corpus reader. ~~JsonlCorpus~~ |
-## Batchers {#batchers source="spacy/training/batchers.py" new="3"}
+## Batchers {id="batchers",source="spacy/training/batchers.py",version="3"}
A data batcher implements a batching strategy that essentially turns a stream of
items into a stream of batches, with each batch consisting of one item or a list
@@ -615,7 +732,7 @@ Instead of using one of the built-in batchers listed here, you can also
[implement your own](/usage/training#custom-code-readers-batchers), which may or
may not use a custom schedule.
-### spacy.batch_by_words.v1 {#batch_by_words tag="registered function"}
+### spacy.batch_by_words.v1 {id="batch_by_words",tag="registered function"}
Create minibatches of roughly a given number of words. If any examples are
longer than the specified batch length, they will appear in a batch by
@@ -643,7 +760,7 @@ themselves, or be discarded if `discard_oversize` is set to `True`. The argument
| `get_length` | Optional function that receives a sequence item and returns its length. Defaults to the built-in `len()` if not set. ~~Optional[Callable[[Any], int]]~~ |
| **CREATES** | The batcher that takes an iterable of items and returns batches. ~~Callable[[Iterable[Any]], Iterable[List[Any]]]~~ |
-### spacy.batch_by_sequence.v1 {#batch_by_sequence tag="registered function"}
+### spacy.batch_by_sequence.v1 {id="batch_by_sequence",tag="registered function"}
> #### Example config
>
@@ -662,7 +779,7 @@ Create a batcher that creates batches of the specified size.
| `get_length` | Optional function that receives a sequence item and returns its length. Defaults to the built-in `len()` if not set. ~~Optional[Callable[[Any], int]]~~ |
| **CREATES** | The batcher that takes an iterable of items and returns batches. ~~Callable[[Iterable[Any]], Iterable[List[Any]]]~~ |
-### spacy.batch_by_padded.v1 {#batch_by_padded tag="registered function"}
+### spacy.batch_by_padded.v1 {id="batch_by_padded",tag="registered function"}
> #### Example config
>
@@ -688,7 +805,7 @@ sequences in the batch.
| `get_length` | Optional function that receives a sequence item and returns its length. Defaults to the built-in `len()` if not set. ~~Optional[Callable[[Any], int]]~~ |
| **CREATES** | The batcher that takes an iterable of items and returns batches. ~~Callable[[Iterable[Any]], Iterable[List[Any]]]~~ |
-## Augmenters {#augmenters source="spacy/training/augment.py" new="3"}
+## Augmenters {id="augmenters",source="spacy/training/augment.py",version="3"}
Data augmentation is the process of applying small modifications to the training
data. It can be especially useful for punctuation and case replacement – for
@@ -697,7 +814,7 @@ variations using regular quotes, or to make the model less sensitive to
capitalization by including a mix of capitalized and lowercase examples. See the
[usage guide](/usage/training#data-augmentation) for details and examples.
-### spacy.orth_variants.v1 {#orth_variants tag="registered function"}
+### spacy.orth_variants.v1 {id="orth_variants",tag="registered function"}
> #### Example config
>
@@ -724,7 +841,7 @@ beyond corpora that don't have smart quotes, or only have smart quotes etc.
| `orth_variants` | A dictionary containing the single and paired orth variants. Typically loaded from a JSON file. See [`en_orth_variants.json`](https://github.com/explosion/spacy-lookups-data/blob/master/spacy_lookups_data/data/en_orth_variants.json) for an example. ~~Dict[str, Dict[List[Union[str, List[str]]]]]~~ |
| **CREATES** | A function that takes the current `nlp` object and an [`Example`](/api/example) and yields augmented `Example` objects. ~~Callable[[Language, Example], Iterator[Example]]~~ |
-### spacy.lower_case.v1 {#lower_case tag="registered function"}
+### spacy.lower_case.v1 {id="lower_case",tag="registered function"}
> #### Example config
>
@@ -743,12 +860,12 @@ useful for making the model less sensitive to capitalization.
| `level` | The percentage of texts that will be augmented. ~~float~~ |
| **CREATES** | A function that takes the current `nlp` object and an [`Example`](/api/example) and yields augmented `Example` objects. ~~Callable[[Language, Example], Iterator[Example]]~~ |
-## Callbacks {#callbacks source="spacy/training/callbacks.py" new="3"}
+## Callbacks {id="callbacks",source="spacy/training/callbacks.py",version="3"}
The config supports [callbacks](/usage/training#custom-code-nlp-callbacks) at
several points in the lifecycle that can be used modify the `nlp` object.
-### spacy.copy_from_base_model.v1 {#copy_from_base_model tag="registered function"}
+### spacy.copy_from_base_model.v1 {id="copy_from_base_model",tag="registered function"}
> #### Example config
>
@@ -772,7 +889,7 @@ from the specified model. Intended for use in `[initialize.before_init]`.
| `vocab` | The pipeline to copy the vocab from. The vocab includes the lookups and vectors. Defaults to `None`. ~~Optional[str]~~ |
| **CREATES** | A function that takes the current `nlp` object and modifies its `tokenizer` and `vocab`. ~~Callable[[Language], None]~~ |
-### spacy.models_with_nvtx_range.v1 {#models_with_nvtx_range tag="registered function"}
+### spacy.models_with_nvtx_range.v1 {id="models_with_nvtx_range",tag="registered function"}
> #### Example config
>
@@ -792,9 +909,30 @@ backprop passes.
| `backprop_color` | Color identifier for backpropagation passes. Defaults to `-1`. ~~int~~ |
| **CREATES** | A function that takes the current `nlp` and wraps forward/backprop passes in NVTX ranges. ~~Callable[[Language], Language]~~ |
-## Training data and alignment {#gold source="spacy/training"}
+### spacy.models_and_pipes_with_nvtx_range.v1 {id="models_and_pipes_with_nvtx_range",tag="registered function",version="3.4"}
-### training.offsets_to_biluo_tags {#offsets_to_biluo_tags tag="function"}
+> #### Example config
+>
+> ```ini
+> [nlp]
+> after_pipeline_creation = {"@callbacks":"spacy.models_and_pipes_with_nvtx_range.v1"}
+> ```
+
+Recursively wrap both the models and methods of each pipe using
+[NVTX](https://nvidia.github.io/NVTX/) range markers. By default, the following
+methods are wrapped: `pipe`, `predict`, `set_annotations`, `update`, `rehearse`,
+`get_loss`, `initialize`, `begin_update`, `finish_update`, `update`.
+
+| Name | Description |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `forward_color` | Color identifier for model forward passes. Defaults to `-1`. ~~int~~ |
+| `backprop_color` | Color identifier for model backpropagation passes. Defaults to `-1`. ~~int~~ |
+| `additional_pipe_functions` | Additional pipeline methods to wrap. Keys are pipeline names and values are lists of method identifiers. Defaults to `None`. ~~Optional[Dict[str, List[str]]]~~ |
+| **CREATES** | A function that takes the current `nlp` and wraps pipe models and methods in NVTX ranges. ~~Callable[[Language], Language]~~ |
+
+## Training data and alignment {id="gold",source="spacy/training"}
+
+### training.offsets_to_biluo_tags {id="offsets_to_biluo_tags",tag="function"}
Encode labelled spans into per-token tags, using the
[BILUO scheme](/usage/linguistic-features#accessing-ner) (Begin, In, Last, Unit,
@@ -831,7 +969,7 @@ This method was previously available as `spacy.gold.biluo_tags_from_offsets`.
| `missing` | The label used for missing values, e.g. if tokenization doesn't align with the entity offsets. Defaults to `"O"`. ~~str~~ |
| **RETURNS** | A list of strings, describing the [BILUO](/usage/linguistic-features#accessing-ner) tags. ~~List[str]~~ |
-### training.biluo_tags_to_offsets {#biluo_tags_to_offsets tag="function"}
+### training.biluo_tags_to_offsets {id="biluo_tags_to_offsets",tag="function"}
Encode per-token tags following the
[BILUO scheme](/usage/linguistic-features#accessing-ner) into entity offsets.
@@ -859,7 +997,7 @@ This method was previously available as `spacy.gold.offsets_from_biluo_tags`.
| `tags` | A sequence of [BILUO](/usage/linguistic-features#accessing-ner) tags with each tag describing one token. Each tag string will be of the form of either `""`, `"O"` or `"{action}-{label}"`, where action is one of `"B"`, `"I"`, `"L"`, `"U"`. ~~List[str]~~ |
| **RETURNS** | A sequence of `(start, end, label)` triples. `start` and `end` will be character-offset integers denoting the slice into the original string. ~~List[Tuple[int, int, str]]~~ |
-### training.biluo_tags_to_spans {#biluo_tags_to_spans tag="function" new="2.1"}
+### training.biluo_tags_to_spans {id="biluo_tags_to_spans",tag="function",version="2.1"}
Encode per-token tags following the
[BILUO scheme](/usage/linguistic-features#accessing-ner) into
@@ -888,7 +1026,103 @@ This method was previously available as `spacy.gold.spans_from_biluo_tags`.
| `tags` | A sequence of [BILUO](/usage/linguistic-features#accessing-ner) tags with each tag describing one token. Each tag string will be of the form of either `""`, `"O"` or `"{action}-{label}"`, where action is one of `"B"`, `"I"`, `"L"`, `"U"`. ~~List[str]~~ |
| **RETURNS** | A sequence of `Span` objects with added entity labels. ~~List[Span]~~ |
-## Utility functions {#util source="spacy/util.py"}
+### training.biluo_to_iob {id="biluo_to_iob",tag="function"}
+
+Convert a sequence of [BILUO](/usage/linguistic-features#accessing-ner) tags to
+[IOB](/usage/linguistic-features#accessing-ner) tags. This is useful if you want
+use the BILUO tags with a model that only supports IOB tags.
+
+> #### Example
+>
+> ```python
+> from spacy.training import biluo_to_iob
+>
+> tags = ["O", "O", "B-LOC", "I-LOC", "L-LOC", "O"]
+> iob_tags = biluo_to_iob(tags)
+> assert iob_tags == ["O", "O", "B-LOC", "I-LOC", "I-LOC", "O"]
+> ```
+
+| Name | Description |
+| ----------- | --------------------------------------------------------------------------------------- |
+| `tags` | A sequence of [BILUO](/usage/linguistic-features#accessing-ner) tags. ~~Iterable[str]~~ |
+| **RETURNS** | A list of [IOB](/usage/linguistic-features#accessing-ner) tags. ~~List[str]~~ |
+
+### training.iob_to_biluo {id="iob_to_biluo",tag="function"}
+
+Convert a sequence of [IOB](/usage/linguistic-features#accessing-ner) tags to
+[BILUO](/usage/linguistic-features#accessing-ner) tags. This is useful if you
+want use the IOB tags with a model that only supports BILUO tags.
+
+
+
+This method was previously available as `spacy.gold.iob_to_biluo`.
+
+
+
+> #### Example
+>
+> ```python
+> from spacy.training import iob_to_biluo
+>
+> tags = ["O", "O", "B-LOC", "I-LOC", "O"]
+> biluo_tags = iob_to_biluo(tags)
+> assert biluo_tags == ["O", "O", "B-LOC", "L-LOC", "O"]
+> ```
+
+| Name | Description |
+| ----------- | ------------------------------------------------------------------------------------- |
+| `tags` | A sequence of [IOB](/usage/linguistic-features#accessing-ner) tags. ~~Iterable[str]~~ |
+| **RETURNS** | A list of [BILUO](/usage/linguistic-features#accessing-ner) tags. ~~List[str]~~ |
+
+### training.biluo_to_iob {id="biluo_to_iob",tag="function"}
+
+Convert a sequence of [BILUO](/usage/linguistic-features#accessing-ner) tags to
+[IOB](/usage/linguistic-features#accessing-ner) tags. This is useful if you want
+use the BILUO tags with a model that only supports IOB tags.
+
+> #### Example
+>
+> ```python
+> from spacy.training import biluo_to_iob
+>
+> tags = ["O", "O", "B-LOC", "I-LOC", "L-LOC", "O"]
+> iob_tags = biluo_to_iob(tags)
+> assert iob_tags == ["O", "O", "B-LOC", "I-LOC", "I-LOC", "O"]
+> ```
+
+| Name | Description |
+| ----------- | --------------------------------------------------------------------------------------- |
+| `tags` | A sequence of [BILUO](/usage/linguistic-features#accessing-ner) tags. ~~Iterable[str]~~ |
+| **RETURNS** | A list of [IOB](/usage/linguistic-features#accessing-ner) tags. ~~List[str]~~ |
+
+### training.iob_to_biluo {id="iob_to_biluo",tag="function"}
+
+Convert a sequence of [IOB](/usage/linguistic-features#accessing-ner) tags to
+[BILUO](/usage/linguistic-features#accessing-ner) tags. This is useful if you
+want use the IOB tags with a model that only supports BILUO tags.
+
+
+
+This method was previously available as `spacy.gold.iob_to_biluo`.
+
+
+
+> #### Example
+>
+> ```python
+> from spacy.training import iob_to_biluo
+>
+> tags = ["O", "O", "B-LOC", "I-LOC", "O"]
+> biluo_tags = iob_to_biluo(tags)
+> assert biluo_tags == ["O", "O", "B-LOC", "L-LOC", "O"]
+> ```
+
+| Name | Description |
+| ----------- | ------------------------------------------------------------------------------------- |
+| `tags` | A sequence of [IOB](/usage/linguistic-features#accessing-ner) tags. ~~Iterable[str]~~ |
+| **RETURNS** | A list of [BILUO](/usage/linguistic-features#accessing-ner) tags. ~~List[str]~~ |
+
+## Utility functions {id="util",source="spacy/util.py"}
spaCy comes with a small collection of utility functions located in
[`spacy/util.py`](%%GITHUB_SPACY/spacy/util.py). Because utility functions are
@@ -898,7 +1132,7 @@ use and we'll try to ensure backwards compatibility. However, we recommend
having additional tests in place if your application depends on any of spaCy's
utilities.
-### util.get_lang_class {#util.get_lang_class tag="function"}
+### util.get_lang_class {id="util.get_lang_class",tag="function"}
Import and load a `Language` class. Allows lazy-loading
[language data](/usage/linguistic-features#language-data) and importing
@@ -919,7 +1153,7 @@ custom language class, you can register it using the
| `lang` | Two-letter language code, e.g. `"en"`. ~~str~~ |
| **RETURNS** | The respective subclass. ~~Language~~ |
-### util.lang_class_is_loaded {#util.lang_class_is_loaded tag="function" new="2.1"}
+### util.lang_class_is_loaded {id="util.lang_class_is_loaded",tag="function",version="2.1"}
Check whether a `Language` subclass is already loaded. `Language` subclasses are
loaded lazily to avoid expensive setup code associated with the language data.
@@ -937,7 +1171,7 @@ loaded lazily to avoid expensive setup code associated with the language data.
| `name` | Two-letter language code, e.g. `"en"`. ~~str~~ |
| **RETURNS** | Whether the class has been loaded. ~~bool~~ |
-### util.load_model {#util.load_model tag="function" new="2"}
+### util.load_model {id="util.load_model",tag="function",version="2"}
Load a pipeline from a package or data path. If called with a string name, spaCy
will assume the pipeline is a Python package and import and call its `load()`
@@ -954,17 +1188,18 @@ and create a `Language` object. The model data will then be loaded in via
> nlp = util.load_model("/path/to/data")
> ```
-| Name | Description |
-| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `name` | Package name or path. ~~str~~ |
-| _keyword-only_ | |
-| `vocab` | Optional shared vocab to pass in on initialization. If `True` (default), a new `Vocab` object will be created. ~~Union[Vocab, bool]~~ |
-| `disable` | Names of pipeline components to [disable](/usage/processing-pipelines#disabling). Disabled pipes will be loaded but they won't be run unless you explicitly enable them by calling [`nlp.enable_pipe`](/api/language#enable_pipe). ~~List[str]~~ |
-| `exclude` 3 | Names of pipeline components to [exclude](/usage/processing-pipelines#disabling). Excluded components won't be loaded. ~~List[str]~~ |
-| `config` 3 | Config overrides as nested dict or flat dict keyed by section values in dot notation, e.g. `"nlp.pipeline"`. ~~Union[Dict[str, Any], Config]~~ |
-| **RETURNS** | `Language` class with the loaded pipeline. ~~Language~~ |
+| Name | Description |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name` | Package name or path. ~~str~~ |
+| _keyword-only_ | |
+| `vocab` | Optional shared vocab to pass in on initialization. If `True` (default), a new `Vocab` object will be created. ~~Union[Vocab, bool]~~ |
+| `disable` | Name(s) of pipeline component(s) to [disable](/usage/processing-pipelines#disabling). Disabled pipes will be loaded but they won't be run unless you explicitly enable them by calling [`nlp.enable_pipe`](/api/language#enable_pipe). ~~Union[str, Iterable[str]]~~ |
+| `enable` 3.4 | Name(s) of pipeline component(s) to [enable](/usage/processing-pipelines#disabling). All other pipes will be disabled, but can be enabled again using [`nlp.enable_pipe`](/api/language#enable_pipe). ~~Union[str, Iterable[str]]~~ |
+| `exclude` | Name(s) of pipeline component(s) to [exclude](/usage/processing-pipelines#disabling). Excluded components won't be loaded. ~~Union[str, Iterable[str]]~~ |
+| `config` 3 | Config overrides as nested dict or flat dict keyed by section values in dot notation, e.g. `"nlp.pipeline"`. ~~Union[Dict[str, Any], Config]~~ |
+| **RETURNS** | `Language` class with the loaded pipeline. ~~Language~~ |
-### util.load_model_from_init_py {#util.load_model_from_init_py tag="function" new="2"}
+### util.load_model_from_init_py {id="util.load_model_from_init_py",tag="function",version="2"}
A helper function to use in the `load()` method of a pipeline package's
[`__init__.py`](https://github.com/explosion/spacy-models/tree/master/template/model/xx_model_name/__init__.py).
@@ -978,17 +1213,18 @@ A helper function to use in the `load()` method of a pipeline package's
> return load_model_from_init_py(__file__, **overrides)
> ```
-| Name | Description |
-| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `init_file` | Path to package's `__init__.py`, i.e. `__file__`. ~~Union[str, Path]~~ |
-| _keyword-only_ | |
-| `vocab` 3 | Optional shared vocab to pass in on initialization. If `True` (default), a new `Vocab` object will be created. ~~Union[Vocab, bool]~~ |
-| `disable` | Names of pipeline components to [disable](/usage/processing-pipelines#disabling). Disabled pipes will be loaded but they won't be run unless you explicitly enable them by calling [nlp.enable_pipe](/api/language#enable_pipe). ~~List[str]~~ |
-| `exclude` 3 | Names of pipeline components to [exclude](/usage/processing-pipelines#disabling). Excluded components won't be loaded. ~~List[str]~~ |
-| `config` 3 | Config overrides as nested dict or flat dict keyed by section values in dot notation, e.g. `"nlp.pipeline"`. ~~Union[Dict[str, Any], Config]~~ |
-| **RETURNS** | `Language` class with the loaded pipeline. ~~Language~~ |
+| Name | Description |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `init_file` | Path to package's `__init__.py`, i.e. `__file__`. ~~Union[str, Path]~~ |
+| _keyword-only_ | |
+| `vocab` 3 | Optional shared vocab to pass in on initialization. If `True` (default), a new `Vocab` object will be created. ~~Union[Vocab, bool]~~ |
+| `disable` | Name(s) of pipeline component(s) to [disable](/usage/processing-pipelines#disabling). Disabled pipes will be loaded but they won't be run unless you explicitly enable them by calling [`nlp.enable_pipe`](/api/language#enable_pipe). ~~Union[str, Iterable[str]]~~ |
+| `enable` 3.4 | Name(s) of pipeline component(s) to [enable](/usage/processing-pipelines#disabling). All other pipes will be disabled, but can be enabled again using [`nlp.enable_pipe`](/api/language#enable_pipe). ~~Union[str, Iterable[str]]~~ |
+| `exclude` 3 | Name(s) of pipeline component(s) to [exclude](/usage/processing-pipelines#disabling). Excluded components won't be loaded. ~~Union[str, Iterable[str]]~~ |
+| `config` 3 | Config overrides as nested dict or flat dict keyed by section values in dot notation, e.g. `"nlp.pipeline"`. ~~Union[Dict[str, Any], Config]~~ |
+| **RETURNS** | `Language` class with the loaded pipeline. ~~Language~~ |
-### util.load_config {#util.load_config tag="function" new="3"}
+### util.load_config {id="util.load_config",tag="function",version="3"}
Load a pipeline's [`config.cfg`](/api/data-formats#config) from a file path. The
config typically includes details about the components and how they're created,
@@ -1008,7 +1244,7 @@ as well as all training settings and hyperparameters.
| `interpolate` | Whether to interpolate the config and replace variables like `${paths.train}` with their values. Defaults to `False`. ~~bool~~ |
| **RETURNS** | The pipeline's config. ~~Config~~ |
-### util.load_meta {#util.load_meta tag="function" new="3"}
+### util.load_meta {id="util.load_meta",tag="function",version="3"}
Get a pipeline's [`meta.json`](/api/data-formats#meta) from a file path and
validate its contents. The meta typically includes details about author,
@@ -1025,7 +1261,7 @@ licensing, data sources and version.
| `path` | Path to the pipeline's `meta.json`. ~~Union[str, Path]~~ |
| **RETURNS** | The pipeline's meta data. ~~Dict[str, Any]~~ |
-### util.get_installed_models {#util.get_installed_models tag="function" new="3"}
+### util.get_installed_models {id="util.get_installed_models",tag="function",version="3"}
List all pipeline packages installed in the current environment. This will
include any spaCy pipeline that was packaged with
@@ -1043,7 +1279,7 @@ object.
| ----------- | ------------------------------------------------------------------------------------- |
| **RETURNS** | The string names of the pipelines installed in the current environment. ~~List[str]~~ |
-### util.is_package {#util.is_package tag="function"}
+### util.is_package {id="util.is_package",tag="function"}
Check if string maps to a package installed via pip. Mainly used to validate
[pipeline packages](/usage/models).
@@ -1060,7 +1296,7 @@ Check if string maps to a package installed via pip. Mainly used to validate
| `name` | Name of package. ~~str~~ |
| **RETURNS** | `True` if installed package, `False` if not. ~~bool~~ |
-### util.get_package_path {#util.get_package_path tag="function" new="2"}
+### util.get_package_path {id="util.get_package_path",tag="function",version="2"}
Get path to an installed package. Mainly used to resolve the location of
[pipeline packages](/usage/models). Currently imports the package to find its
@@ -1078,7 +1314,7 @@ path.
| `package_name` | Name of installed package. ~~str~~ |
| **RETURNS** | Path to pipeline package directory. ~~Path~~ |
-### util.is_in_jupyter {#util.is_in_jupyter tag="function" new="2"}
+### util.is_in_jupyter {id="util.is_in_jupyter",tag="function",version="2"}
Check if user is running spaCy from a [Jupyter](https://jupyter.org) notebook by
detecting the IPython kernel. Mainly used for the
@@ -1097,7 +1333,7 @@ detecting the IPython kernel. Mainly used for the
| ----------- | ---------------------------------------------- |
| **RETURNS** | `True` if in Jupyter, `False` if not. ~~bool~~ |
-### util.compile_prefix_regex {#util.compile_prefix_regex tag="function"}
+### util.compile_prefix_regex {id="util.compile_prefix_regex",tag="function"}
Compile a sequence of prefix rules into a regex object.
@@ -1114,7 +1350,7 @@ Compile a sequence of prefix rules into a regex object.
| `entries` | The prefix rules, e.g. [`lang.punctuation.TOKENIZER_PREFIXES`](%%GITHUB_SPACY/spacy/lang/punctuation.py). ~~Iterable[Union[str, Pattern]]~~ |
| **RETURNS** | The regex object to be used for [`Tokenizer.prefix_search`](/api/tokenizer#attributes). ~~Pattern~~ |
-### util.compile_suffix_regex {#util.compile_suffix_regex tag="function"}
+### util.compile_suffix_regex {id="util.compile_suffix_regex",tag="function"}
Compile a sequence of suffix rules into a regex object.
@@ -1131,7 +1367,7 @@ Compile a sequence of suffix rules into a regex object.
| `entries` | The suffix rules, e.g. [`lang.punctuation.TOKENIZER_SUFFIXES`](%%GITHUB_SPACY/spacy/lang/punctuation.py). ~~Iterable[Union[str, Pattern]]~~ |
| **RETURNS** | The regex object to be used for [`Tokenizer.suffix_search`](/api/tokenizer#attributes). ~~Pattern~~ |
-### util.compile_infix_regex {#util.compile_infix_regex tag="function"}
+### util.compile_infix_regex {id="util.compile_infix_regex",tag="function"}
Compile a sequence of infix rules into a regex object.
@@ -1148,7 +1384,7 @@ Compile a sequence of infix rules into a regex object.
| `entries` | The infix rules, e.g. [`lang.punctuation.TOKENIZER_INFIXES`](%%GITHUB_SPACY/spacy/lang/punctuation.py). ~~Iterable[Union[str, Pattern]]~~ |
| **RETURNS** | The regex object to be used for [`Tokenizer.infix_finditer`](/api/tokenizer#attributes). ~~Pattern~~ |
-### util.minibatch {#util.minibatch tag="function" new="2"}
+### util.minibatch {id="util.minibatch",tag="function",version="2"}
Iterate over batches of items. `size` may be an iterator, so that batch-size can
vary on each step.
@@ -1167,7 +1403,7 @@ vary on each step.
| `size` | The batch size(s). ~~Union[int, Sequence[int]]~~ |
| **YIELDS** | The batches. |
-### util.filter_spans {#util.filter_spans tag="function" new="2.1.4"}
+### util.filter_spans {id="util.filter_spans",tag="function",version="2.1.4"}
Filter a sequence of [`Span`](/api/span) objects and remove duplicates or
overlaps. Useful for creating named entities (where one token can only be part
@@ -1188,7 +1424,7 @@ of one entity) or when merging spans with
| `spans` | The spans to filter. ~~Iterable[Span]~~ |
| **RETURNS** | The filtered spans. ~~List[Span]~~ |
-### util.get_words_and_spaces {#get_words_and_spaces tag="function" new="3"}
+### util.get_words_and_spaces {id="get_words_and_spaces",tag="function",version="3"}
Given a list of words and a text, reconstruct the original tokens and return a
list of words and spaces that can be used to create a [`Doc`](/api/doc#init).
diff --git a/website/docs/api/transformer.md b/website/docs/api/transformer.mdx
similarity index 93%
rename from website/docs/api/transformer.md
rename to website/docs/api/transformer.mdx
index b1673cdbe..ad8ecce54 100644
--- a/website/docs/api/transformer.md
+++ b/website/docs/api/transformer.mdx
@@ -3,7 +3,7 @@ title: Transformer
teaser: Pipeline component for multi-task learning with transformer models
tag: class
source: github.com/explosion/spacy-transformers/blob/master/spacy_transformers/pipeline_component.py
-new: 3
+version: 3
api_base_class: /api/pipe
api_string_name: transformer
---
@@ -44,7 +44,7 @@ package also adds the function registries [`@span_getters`](#span_getters) and
functions. For more details, see the
[usage documentation](/usage/embeddings-transformers).
-## Assigned Attributes {#assigned-attributes}
+## Assigned Attributes {id="assigned-attributes"}
The component sets the following
[custom extension attribute](/usage/processing-pipeline#custom-components-attributes):
@@ -53,7 +53,7 @@ The component sets the following
| ---------------- | ------------------------------------------------------------------------ |
| `Doc._.trf_data` | Transformer tokens and outputs for the `Doc` object. ~~TransformerData~~ |
-## Config and implementation {#config}
+## Config and implementation {id="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
@@ -81,7 +81,7 @@ on the transformer architectures and their arguments and hyperparameters.
https://github.com/explosion/spacy-transformers/blob/master/spacy_transformers/pipeline_component.py
```
-## Transformer.\_\_init\_\_ {#init tag="method"}
+## Transformer.\_\_init\_\_ {id="init",tag="method"}
> #### Example
>
@@ -124,7 +124,7 @@ component using its string name and [`nlp.add_pipe`](/api/language#create_pipe).
| `name` | String name of the component instance. Used to add entries to the `losses` during training. ~~str~~ |
| `max_batch_items` | Maximum size of a padded batch. Defaults to `128*32`. ~~int~~ |
-## Transformer.\_\_call\_\_ {#call tag="method"}
+## Transformer.\_\_call\_\_ {id="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
@@ -147,7 +147,7 @@ to the [`predict`](/api/transformer#predict) and
| `doc` | The document to process. ~~Doc~~ |
| **RETURNS** | The processed document. ~~Doc~~ |
-## Transformer.pipe {#pipe tag="method"}
+## Transformer.pipe {id="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
@@ -171,14 +171,14 @@ applied to the `Doc` in order. Both [`__call__`](/api/transformer#call) and
| `batch_size` | The number of documents to buffer. Defaults to `128`. ~~int~~ |
| **YIELDS** | The processed documents in order. ~~Doc~~ |
-## Transformer.initialize {#initialize tag="method"}
+## Transformer.initialize {id="initialize",tag="method"}
Initialize the component for training and return an
[`Optimizer`](https://thinc.ai/docs/api-optimizers). `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,
+function that 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).
@@ -187,16 +187,16 @@ by [`Language.initialize`](/api/language#initialize).
>
> ```python
> trf = nlp.add_pipe("transformer")
-> trf.initialize(lambda: iter([]), nlp=nlp)
+> trf.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]~~ |
-## Transformer.predict {#predict tag="method"}
+## Transformer.predict {id="predict",tag="method"}
Apply the component's model to a batch of [`Doc`](/api/doc) objects without
modifying them.
@@ -213,7 +213,7 @@ modifying them.
| `docs` | The documents to predict. ~~Iterable[Doc]~~ |
| **RETURNS** | The model's prediction for each document. |
-## Transformer.set_annotations {#set_annotations tag="method"}
+## Transformer.set_annotations {id="set_annotations",tag="method"}
Assign the extracted features to the `Doc` objects. By default, the
[`TransformerData`](/api/transformer#transformerdata) object is written to the
@@ -233,7 +233,7 @@ callback is then called, if provided.
| `docs` | The documents to modify. ~~Iterable[Doc]~~ |
| `scores` | The scores to set, produced by `Transformer.predict`. |
-## Transformer.update {#update tag="method"}
+## Transformer.update {id="update",tag="method"}
Prepare for an update to the transformer. Like the [`Tok2Vec`](/api/tok2vec)
component, the `Transformer` component is unusual in that it does not receive
@@ -266,7 +266,7 @@ and call the optimizer, while the others simply increment the gradients.
| `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]~~ |
-## Transformer.create_optimizer {#create_optimizer tag="method"}
+## Transformer.create_optimizer {id="create_optimizer",tag="method"}
Create an optimizer for the pipeline component.
@@ -281,7 +281,7 @@ Create an optimizer for the pipeline component.
| ----------- | ---------------------------- |
| **RETURNS** | The optimizer. ~~Optimizer~~ |
-## Transformer.use_params {#use_params tag="method, contextmanager"}
+## Transformer.use_params {id="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.
@@ -298,7 +298,7 @@ context, the original parameters are restored.
| -------- | -------------------------------------------------- |
| `params` | The parameter values to use in the model. ~~dict~~ |
-## Transformer.to_disk {#to_disk tag="method"}
+## Transformer.to_disk {id="to_disk",tag="method"}
Serialize the pipe to disk.
@@ -315,7 +315,7 @@ Serialize the pipe to disk.
| _keyword-only_ | |
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
-## Transformer.from_disk {#from_disk tag="method"}
+## Transformer.from_disk {id="from_disk",tag="method"}
Load the pipe from disk. Modifies the object in place and returns it.
@@ -333,7 +333,7 @@ Load the pipe from disk. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The modified `Transformer` object. ~~Transformer~~ |
-## Transformer.to_bytes {#to_bytes tag="method"}
+## Transformer.to_bytes {id="to_bytes",tag="method"}
> #### Example
>
@@ -350,7 +350,7 @@ Serialize the pipe to a bytestring.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The serialized form of the `Transformer` object. ~~bytes~~ |
-## Transformer.from_bytes {#from_bytes tag="method"}
+## Transformer.from_bytes {id="from_bytes",tag="method"}
Load the pipe from a bytestring. Modifies the object in place and returns it.
@@ -369,7 +369,7 @@ Load the pipe from a bytestring. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The `Transformer` object. ~~Transformer~~ |
-## Serialization fields {#serialization-fields}
+## Serialization fields {id="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
@@ -387,7 +387,7 @@ serialization by passing in the string names via the `exclude` argument.
| `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. |
-## TransformerData {#transformerdata tag="dataclass"}
+## TransformerData {id="transformerdata",tag="dataclass"}
Transformer tokens and outputs for one `Doc` object. The transformer models
return tensors that refer to a whole padded batch of documents. These tensors
@@ -405,7 +405,7 @@ by this class. Instances of this class are typically assigned to the
| `align` | Alignment from the `Doc`'s tokenization to the wordpieces. This is a ragged array, where `align.lengths[i]` indicates the number of wordpiece tokens that token `i` aligns against. The actual indices are provided at `align[i].dataXd`. ~~Ragged~~ |
| `width` | The width of the last hidden layer. ~~int~~ |
-### TransformerData.empty {#transformerdata-emoty tag="classmethod"}
+### TransformerData.empty {id="transformerdata-emoty",tag="classmethod"}
Create an empty `TransformerData` container.
@@ -425,7 +425,7 @@ model.
-## FullTransformerBatch {#fulltransformerbatch tag="dataclass"}
+## FullTransformerBatch {id="fulltransformerbatch",tag="dataclass"}
Holds a batch of input and output objects for a transformer model. The data can
then be split to a list of [`TransformerData`](/api/transformer#transformerdata)
@@ -440,7 +440,7 @@ objects to associate the outputs to each [`Doc`](/api/doc) in the batch.
| `align` | Alignment from the spaCy tokenization to the wordpieces. This is a ragged array, where `align.lengths[i]` indicates the number of wordpiece tokens that token `i` aligns against. The actual indices are provided at `align[i].dataXd`. ~~Ragged~~ |
| `doc_data` | The outputs, split per `Doc` object. ~~List[TransformerData]~~ |
-### FullTransformerBatch.unsplit_by_doc {#fulltransformerbatch-unsplit_by_doc tag="method"}
+### FullTransformerBatch.unsplit_by_doc {id="fulltransformerbatch-unsplit_by_doc",tag="method"}
Return a new `FullTransformerBatch` from a split batch of activations, using the
current object's spans, tokens and alignment. This is used during the backward
@@ -452,7 +452,7 @@ model.
| `arrays` | The split batch of activations. ~~List[List[Floats3d]]~~ |
| **RETURNS** | The transformer batch. ~~FullTransformerBatch~~ |
-### FullTransformerBatch.split_by_doc {#fulltransformerbatch-split_by_doc tag="method"}
+### FullTransformerBatch.split_by_doc {id="fulltransformerbatch-split_by_doc",tag="method"}
Split a `TransformerData` object that represents a batch into a list with one
`TransformerData` per `Doc`.
@@ -468,7 +468,7 @@ In `spacy-transformers` v1.0, the model output is stored in
-## Span getters {#span_getters source="github.com/explosion/spacy-transformers/blob/master/spacy_transformers/span_getters.py"}
+## Span getters {id="span_getters",source="github.com/explosion/spacy-transformers/blob/master/spacy_transformers/span_getters.py"}
Span getters are functions that take a batch of [`Doc`](/api/doc) objects and
return a lists of [`Span`](/api/span) objects for each doc to be processed by
@@ -498,7 +498,7 @@ using the `@spacy.registry.span_getters` decorator.
| `docs` | A batch of `Doc` objects. ~~Iterable[Doc]~~ |
| **RETURNS** | The spans to process by the transformer. ~~List[List[Span]]~~ |
-### doc_spans.v1 {#doc_spans tag="registered function"}
+### doc_spans.v1 {id="doc_spans",tag="registered function"}
> #### Example config
>
@@ -511,7 +511,7 @@ Create a span getter that uses the whole document as its spans. This is the best
approach if your [`Doc`](/api/doc) objects already refer to relatively short
texts.
-### sent_spans.v1 {#sent_spans tag="registered function"}
+### sent_spans.v1 {id="sent_spans",tag="registered function"}
> #### Example config
>
@@ -531,7 +531,7 @@ To set sentence boundaries with the `sentencizer` during training, add a
[`[training.annotating_components]`](/usage/training#annotating-components) to
have it set the sentence boundaries before the `transformer` component runs.
-### strided_spans.v1 {#strided_spans tag="registered function"}
+### strided_spans.v1 {id="strided_spans",tag="registered function"}
> #### Example config
>
@@ -553,7 +553,7 @@ right context.
| `window` | The window size. ~~int~~ |
| `stride` | The stride size. ~~int~~ |
-## Annotation setters {#annotation_setters tag="registered functions" source="github.com/explosion/spacy-transformers/blob/master/spacy_transformers/annotation_setters.py"}
+## Annotation setters {id="annotation_setters",tag="registered functions",source="github.com/explosion/spacy-transformers/blob/master/spacy_transformers/annotation_setters.py"}
Annotation setters are functions that take a batch of `Doc` objects and a
[`FullTransformerBatch`](/api/transformer#fulltransformerbatch) and can set
diff --git a/website/docs/api/vectors.md b/website/docs/api/vectors.mdx
similarity index 91%
rename from website/docs/api/vectors.md
rename to website/docs/api/vectors.mdx
index a651c23b0..d6033c096 100644
--- a/website/docs/api/vectors.md
+++ b/website/docs/api/vectors.mdx
@@ -3,7 +3,7 @@ title: Vectors
teaser: Store, save and load word vectors
tag: class
source: spacy/vectors.pyx
-new: 2
+version: 2
---
Vectors data is kept in the `Vectors.data` attribute, which should be an
@@ -25,7 +25,7 @@ As of spaCy v3.2, `Vectors` supports two types of vector tables:
the sum of one or more rows as determined by the settings related to character
ngrams and the hash table.
-## Vectors.\_\_init\_\_ {#init tag="method"}
+## Vectors.\_\_init\_\_ {id="init",tag="method"}
Create a new vector store. With the default mode, you can set the vector values
and keys directly on initialization, or supply a `shape` keyword argument to
@@ -50,7 +50,7 @@ modified later.
| _keyword-only_ | |
| `strings` | The string store. A new string store is created if one is not provided. Defaults to `None`. ~~Optional[StringStore]~~ |
| `shape` | Size of the table as `(n_entries, n_columns)`, the number of entries and number of columns. Not required if you're initializing the object with `data` and `keys`. ~~Tuple[int, int]~~ |
-| `data` | The vector data. ~~numpy.ndarray[ndim=1, dtype=float32]~~ |
+| `data` | The vector data. ~~numpy.ndarray[ndim=2, dtype=float32]~~ |
| `keys` | A sequence of keys aligned with the data. ~~Iterable[Union[str, int]]~~ |
| `name` | A name to identify the vectors table. ~~str~~ |
| `mode` 3.2 | Vectors mode: `"default"` or [`"floret"`](https://github.com/explosion/floret) (default: `"default"`). ~~str~~ |
@@ -61,7 +61,7 @@ modified later.
| `bow` 3.2 | The floret BOW string (default: `"<"`). ~~str~~ |
| `eow` 3.2 | The floret EOW string (default: `">"`). ~~str~~ |
-## Vectors.\_\_getitem\_\_ {#getitem tag="method"}
+## Vectors.\_\_getitem\_\_ {id="getitem",tag="method"}
Get a vector by key. If the key is not found in the table, a `KeyError` is
raised.
@@ -79,7 +79,7 @@ raised.
| `key` | The key to get the vector for. ~~Union[int, str]~~ |
| **RETURNS** | The vector for the key. ~~numpy.ndarray[ndim=1, dtype=float32]~~ |
-## Vectors.\_\_setitem\_\_ {#setitem tag="method"}
+## Vectors.\_\_setitem\_\_ {id="setitem",tag="method"}
Set a vector for the given key. Not supported for `floret` mode.
@@ -96,7 +96,7 @@ Set a vector for the given key. Not supported for `floret` mode.
| `key` | The key to set the vector for. ~~int~~ |
| `vector` | The vector to set. ~~numpy.ndarray[ndim=1, dtype=float32]~~ |
-## Vectors.\_\_iter\_\_ {#iter tag="method"}
+## Vectors.\_\_iter\_\_ {id="iter",tag="method"}
Iterate over the keys in the table. In `floret` mode, the keys table is not
used.
@@ -112,7 +112,7 @@ used.
| ---------- | --------------------------- |
| **YIELDS** | A key in the table. ~~int~~ |
-## Vectors.\_\_len\_\_ {#len tag="method"}
+## Vectors.\_\_len\_\_ {id="len",tag="method"}
Return the number of vectors in the table.
@@ -127,7 +127,7 @@ Return the number of vectors in the table.
| ----------- | ------------------------------------------- |
| **RETURNS** | The number of vectors in the table. ~~int~~ |
-## Vectors.\_\_contains\_\_ {#contains tag="method"}
+## Vectors.\_\_contains\_\_ {id="contains",tag="method"}
Check whether a key has been mapped to a vector entry in the table. In `floret`
mode, returns `True` for all keys.
@@ -145,7 +145,7 @@ mode, returns `True` for all keys.
| `key` | The key to check. ~~int~~ |
| **RETURNS** | Whether the key has a vector entry. ~~bool~~ |
-## Vectors.add {#add tag="method"}
+## Vectors.add {id="add",tag="method"}
Add a key to the table, optionally setting a vector value as well. Keys can be
mapped to an existing vector by setting `row`, or a new vector can be added. Not
@@ -168,7 +168,7 @@ supported for `floret` mode.
| `row` | An optional row number of a vector to map the key to. ~~int~~ |
| **RETURNS** | The row the vector was added to. ~~int~~ |
-## Vectors.resize {#resize tag="method"}
+## Vectors.resize {id="resize",tag="method"}
Resize the underlying vectors array. If `inplace=True`, the memory is
reallocated. This may cause other references to the data to become invalid, so
@@ -189,7 +189,7 @@ for `floret` mode.
| `inplace` | Reallocate the memory. ~~bool~~ |
| **RETURNS** | The removed items as a list of `(key, row)` tuples. ~~List[Tuple[int, int]]~~ |
-## Vectors.keys {#keys tag="method"}
+## Vectors.keys {id="keys",tag="method"}
A sequence of the keys in the table. In `floret` mode, the keys table is not
used.
@@ -205,7 +205,7 @@ used.
| ----------- | --------------------------- |
| **RETURNS** | The keys. ~~Iterable[int]~~ |
-## Vectors.values {#values tag="method"}
+## Vectors.values {id="values",tag="method"}
Iterate over vectors that have been assigned to at least one key. Note that some
vectors may be unassigned, so the number of vectors returned may be less than
@@ -222,7 +222,7 @@ the length of the vectors table. In `floret` mode, the keys table is not used.
| ---------- | --------------------------------------------------------------- |
| **YIELDS** | A vector in the table. ~~numpy.ndarray[ndim=1, dtype=float32]~~ |
-## Vectors.items {#items tag="method"}
+## Vectors.items {id="items",tag="method"}
Iterate over `(key, vector)` pairs, in order. In `floret` mode, the keys table
is empty.
@@ -238,7 +238,7 @@ is empty.
| ---------- | ------------------------------------------------------------------------------------- |
| **YIELDS** | `(key, vector)` pairs, in order. ~~Tuple[int, numpy.ndarray[ndim=1, dtype=float32]]~~ |
-## Vectors.find {#find tag="method"}
+## Vectors.find {id="find",tag="method"}
Look up one or more keys by row, or vice versa. Not supported for `floret` mode.
@@ -260,7 +260,7 @@ Look up one or more keys by row, or vice versa. Not supported for `floret` mode.
| `rows` | Find the keys that point to the rows. Returns `numpy.ndarray`. ~~Iterable[int]~~ |
| **RETURNS** | The requested key, keys, row or rows. ~~Union[int, numpy.ndarray[ndim=1, dtype=float32]]~~ |
-## Vectors.shape {#shape tag="property"}
+## Vectors.shape {id="shape",tag="property"}
Get `(rows, dims)` tuples of number of rows and number of dimensions in the
vector table.
@@ -279,7 +279,7 @@ vector table.
| ----------- | ------------------------------------------ |
| **RETURNS** | A `(rows, dims)` pair. ~~Tuple[int, int]~~ |
-## Vectors.size {#size tag="property"}
+## Vectors.size {id="size",tag="property"}
The vector size, i.e. `rows * dims`.
@@ -294,7 +294,7 @@ The vector size, i.e. `rows * dims`.
| ----------- | ------------------------ |
| **RETURNS** | The vector size. ~~int~~ |
-## Vectors.is_full {#is_full tag="property"}
+## Vectors.is_full {id="is_full",tag="property"}
Whether the vectors table is full and has no slots are available for new keys.
If a table is full, it can be resized using
@@ -313,7 +313,7 @@ full and cannot be resized.
| ----------- | ------------------------------------------- |
| **RETURNS** | Whether the vectors table is full. ~~bool~~ |
-## Vectors.n_keys {#n_keys tag="property"}
+## Vectors.n_keys {id="n_keys",tag="property"}
Get the number of keys in the table. Note that this is the number of _all_ keys,
not just unique vectors. If several keys are mapped to the same vectors, they
@@ -331,7 +331,7 @@ will be counted individually. In `floret` mode, the keys table is not used.
| ----------- | ----------------------------------------------------------------------------- |
| **RETURNS** | The number of all keys in the table. Returns `-1` for floret vectors. ~~int~~ |
-## Vectors.most_similar {#most_similar tag="method"}
+## Vectors.most_similar {id="most_similar",tag="method"}
For each of the given vectors, find the `n` most similar entries to it by
cosine. Queries are by vector. Results are returned as a
@@ -347,16 +347,16 @@ supported for `floret` mode.
> most_similar = nlp.vocab.vectors.most_similar(queries, n=10)
> ```
-| Name | Description |
-| -------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `queries` | An array with one or more vectors. ~~numpy.ndarray~~ |
-| _keyword-only_ | |
-| `batch_size` | The batch size to use. Default to `1024`. ~~int~~ |
-| `n` | The number of entries to return for each query. Defaults to `1`. ~~int~~ |
-| `sort` | Whether to sort the entries returned by score. Defaults to `True`. ~~bool~~ |
-| **RETURNS** | tuple | The most similar entries as a `(keys, best_rows, scores)` tuple. ~~Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]~~ |
+| Name | Description |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `queries` | An array with one or more vectors. ~~numpy.ndarray~~ |
+| _keyword-only_ | |
+| `batch_size` | The batch size to use. Default to `1024`. ~~int~~ |
+| `n` | The number of entries to return for each query. Defaults to `1`. ~~int~~ |
+| `sort` | Whether to sort the entries returned by score. Defaults to `True`. ~~bool~~ |
+| **RETURNS** | The most similar entries as a `(keys, best_rows, scores)` tuple. ~~Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]~~ |
-## Vectors.get_batch {#get_batch tag="method" new="3.2"}
+## Vectors.get_batch {id="get_batch",tag="method",version="3.2"}
Get the vectors for the provided keys efficiently as a batch.
@@ -371,7 +371,7 @@ Get the vectors for the provided keys efficiently as a batch.
| ------ | --------------------------------------- |
| `keys` | The keys. ~~Iterable[Union[int, str]]~~ |
-## Vectors.to_ops {#to_ops tag="method"}
+## Vectors.to_ops {id="to_ops",tag="method"}
Change the embedding matrix to use different Thinc ops.
@@ -388,7 +388,7 @@ Change the embedding matrix to use different Thinc ops.
| ----- | -------------------------------------------------------- |
| `ops` | The Thinc ops to switch the embedding matrix to. ~~Ops~~ |
-## Vectors.to_disk {#to_disk tag="method"}
+## Vectors.to_disk {id="to_disk",tag="method"}
Save the current state to a directory.
@@ -403,7 +403,7 @@ Save the current state to a directory.
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `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]~~ |
-## Vectors.from_disk {#from_disk tag="method"}
+## Vectors.from_disk {id="from_disk",tag="method"}
Loads state from a directory. Modifies the object in place and returns it.
@@ -419,7 +419,7 @@ Loads state from a directory. Modifies the object in place and returns it.
| `path` | A path to a directory. Paths may be either strings or `Path`-like objects. ~~Union[str, Path]~~ |
| **RETURNS** | The modified `Vectors` object. ~~Vectors~~ |
-## Vectors.to_bytes {#to_bytes tag="method"}
+## Vectors.to_bytes {id="to_bytes",tag="method"}
Serialize the current state to a binary string.
@@ -433,7 +433,7 @@ Serialize the current state to a binary string.
| ----------- | ------------------------------------------------------ |
| **RETURNS** | The serialized form of the `Vectors` object. ~~bytes~~ |
-## Vectors.from_bytes {#from_bytes tag="method"}
+## Vectors.from_bytes {id="from_bytes",tag="method"}
Load state from a binary string.
@@ -451,7 +451,7 @@ Load state from a binary string.
| `data` | The data to load from. ~~bytes~~ |
| **RETURNS** | The `Vectors` object. ~~Vectors~~ |
-## Attributes {#attributes}
+## Attributes {id="attributes"}
| Name | Description |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
diff --git a/website/docs/api/vocab.md b/website/docs/api/vocab.mdx
similarity index 75%
rename from website/docs/api/vocab.md
rename to website/docs/api/vocab.mdx
index c0a269d95..131e4ce0a 100644
--- a/website/docs/api/vocab.md
+++ b/website/docs/api/vocab.mdx
@@ -10,7 +10,7 @@ The `Vocab` object provides a lookup table that allows you to access
[`StringStore`](/api/stringstore). It also owns underlying C-data that is shared
between `Doc` objects.
-## Vocab.\_\_init\_\_ {#init tag="method"}
+## Vocab.\_\_init\_\_ {id="init",tag="method"}
Create the vocabulary.
@@ -21,17 +21,17 @@ Create the vocabulary.
> vocab = Vocab(strings=["hello", "world"])
> ```
-| Name | Description |
-| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `lex_attr_getters` | A dictionary mapping attribute IDs to functions to compute them. Defaults to `None`. ~~Optional[Dict[str, Callable[[str], Any]]]~~ |
-| `strings` | A [`StringStore`](/api/stringstore) that maps strings to hash values, and vice versa, or a list of strings. ~~Union[List[str], StringStore]~~ |
-| `lookups` | A [`Lookups`](/api/lookups) that stores the `lexeme_norm` and other large lookup tables. Defaults to `None`. ~~Optional[Lookups]~~ |
-| `oov_prob` | The default OOV probability. Defaults to `-20.0`. ~~float~~ |
-| `vectors_name` 2.2 | A name to identify the vectors table. ~~str~~ |
-| `writing_system` | A dictionary describing the language's writing system. Typically provided by [`Language.Defaults`](/api/language#defaults). ~~Dict[str, Any]~~ |
-| `get_noun_chunks` | A function that yields base noun phrases used for [`Doc.noun_chunks`](/api/doc#noun_chunks). ~~Optional[Callable[[Union[Doc, Span], Iterator[Tuple[int, int, int]]]]]~~ |
+| Name | Description |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `lex_attr_getters` | A dictionary mapping attribute IDs to functions to compute them. Defaults to `None`. ~~Optional[Dict[str, Callable[[str], Any]]]~~ |
+| `strings` | A [`StringStore`](/api/stringstore) that maps strings to hash values, and vice versa, or a list of strings. ~~Union[List[str], StringStore]~~ |
+| `lookups` | A [`Lookups`](/api/lookups) that stores the `lexeme_norm` and other large lookup tables. Defaults to `None`. ~~Optional[Lookups]~~ |
+| `oov_prob` | The default OOV probability. Defaults to `-20.0`. ~~float~~ |
+| `vectors_name` | A name to identify the vectors table. ~~str~~ |
+| `writing_system` | A dictionary describing the language's writing system. Typically provided by [`Language.Defaults`](/api/language#defaults). ~~Dict[str, Any]~~ |
+| `get_noun_chunks` | A function that yields base noun phrases used for [`Doc.noun_chunks`](/api/doc#noun_chunks). ~~Optional[Callable[[Union[Doc, Span], Iterator[Tuple[int, int, int]]]]]~~ |
-## Vocab.\_\_len\_\_ {#len tag="method"}
+## Vocab.\_\_len\_\_ {id="len",tag="method"}
Get the current number of lexemes in the vocabulary.
@@ -46,7 +46,7 @@ Get the current number of lexemes in the vocabulary.
| ----------- | ------------------------------------------------ |
| **RETURNS** | The number of lexemes in the vocabulary. ~~int~~ |
-## Vocab.\_\_getitem\_\_ {#getitem tag="method"}
+## Vocab.\_\_getitem\_\_ {id="getitem",tag="method"}
Retrieve a lexeme, given an int ID or a string. If a previously unseen string is
given, a new lexeme is created and stored.
@@ -63,7 +63,7 @@ given, a new lexeme is created and stored.
| `id_or_string` | The hash value of a word, or its string. ~~Union[int, str]~~ |
| **RETURNS** | The lexeme indicated by the given ID. ~~Lexeme~~ |
-## Vocab.\_\_iter\_\_ {#iter tag="method"}
+## Vocab.\_\_iter\_\_ {id="iter",tag="method"}
Iterate over the lexemes in the vocabulary.
@@ -77,7 +77,7 @@ Iterate over the lexemes in the vocabulary.
| ---------- | -------------------------------------- |
| **YIELDS** | An entry in the vocabulary. ~~Lexeme~~ |
-## Vocab.\_\_contains\_\_ {#contains tag="method"}
+## Vocab.\_\_contains\_\_ {id="contains",tag="method"}
Check whether the string has an entry in the vocabulary. To get the ID for a
given string, you need to look it up in
@@ -97,7 +97,7 @@ given string, you need to look it up in
| `string` | The ID string. ~~str~~ |
| **RETURNS** | Whether the string has an entry in the vocabulary. ~~bool~~ |
-## Vocab.add_flag {#add_flag tag="method"}
+## Vocab.add_flag {id="add_flag",tag="method"}
Set a new boolean flag to words in the vocabulary. The `flag_getter` function
will be called over the words currently in the vocab, and then applied to new
@@ -122,7 +122,7 @@ using `token.check_flag(flag_id)`.
| `flag_id` | An integer between `1` and `63` (inclusive), specifying the bit at which the flag will be stored. If `-1`, the lowest available bit will be chosen. ~~int~~ |
| **RETURNS** | The integer ID by which the flag value can be checked. ~~int~~ |
-## Vocab.reset_vectors {#reset_vectors tag="method" new="2"}
+## Vocab.reset_vectors {id="reset_vectors",tag="method",version="2"}
Drop the current vector table. Because all vectors must be the same width, you
have to call this to change the size of the vectors. Only one of the `width` and
@@ -140,7 +140,7 @@ have to call this to change the size of the vectors. Only one of the `width` and
| `width` | The new width. ~~int~~ |
| `shape` | The new shape. ~~int~~ |
-## Vocab.prune_vectors {#prune_vectors tag="method" new="2"}
+## Vocab.prune_vectors {id="prune_vectors",tag="method",version="2"}
Reduce the current vector table to `nr_row` unique entries. Words mapped to the
discarded vectors will be remapped to the closest vector among those remaining.
@@ -156,7 +156,7 @@ cosines are calculated in minibatches to reduce memory usage.
>
> ```python
> nlp.vocab.prune_vectors(10000)
-> assert len(nlp.vocab.vectors) <= 1000
+> assert len(nlp.vocab.vectors) <= 10000
> ```
| Name | Description |
@@ -165,28 +165,36 @@ cosines are calculated in minibatches to reduce memory usage.
| `batch_size` | Batch of vectors for calculating the similarities. Larger batch sizes might be faster, while temporarily requiring more memory. ~~int~~ |
| **RETURNS** | A dictionary keyed by removed words mapped to `(string, score)` tuples, where `string` is the entry the removed word was mapped to, and `score` the similarity score between the two words. ~~Dict[str, Tuple[str, float]]~~ |
-## Vocab.get_vector {#get_vector tag="method" new="2"}
+## Vocab.deduplicate_vectors {id="deduplicate_vectors",tag="method",version="3.3"}
+
+> #### Example
+>
+> ```python
+> nlp.vocab.deduplicate_vectors()
+> ```
+
+Remove any duplicate rows from the current vector table, maintaining the
+mappings for all words in the vectors.
+
+## Vocab.get_vector {id="get_vector",tag="method",version="2"}
Retrieve a vector for a word in the vocabulary. Words can be looked up by string
-or hash value. If no vectors data is loaded, a `ValueError` is raised. If `minn`
-is defined, then the resulting vector uses [FastText](https://fasttext.cc/)'s
-subword features by average over n-grams of `orth` (introduced in spaCy `v2.1`).
+or hash value. If the current vectors do not contain an entry for the word, a
+0-vector with the same number of dimensions
+([`Vocab.vectors_length`](#attributes)) as the current vectors is returned.
> #### Example
>
> ```python
> nlp.vocab.get_vector("apple")
-> nlp.vocab.get_vector("apple", minn=1, maxn=5)
> ```
-| Name | Description |
-| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `orth` | The hash value of a word, or its unicode string. ~~Union[int, str]~~ |
-| `minn` 2.1 | Minimum n-gram length used for FastText's n-gram computation. Defaults to the length of `orth`. ~~int~~ |
-| `maxn` 2.1 | Maximum n-gram length used for FastText's n-gram computation. Defaults to the length of `orth`. ~~int~~ |
-| **RETURNS** | A word vector. Size and shape are determined by the `Vocab.vectors` instance. ~~numpy.ndarray[ndim=1, dtype=float32]~~ |
+| Name | Description |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `orth` | The hash value of a word, or its unicode string. ~~Union[int, str]~~ |
+| **RETURNS** | A word vector. Size and shape are determined by the `Vocab.vectors` instance. ~~numpy.ndarray[ndim=1, dtype=float32]~~ |
-## Vocab.set_vector {#set_vector tag="method" new="2"}
+## Vocab.set_vector {id="set_vector",tag="method",version="2"}
Set a vector for a word in the vocabulary. Words can be referenced by string or
hash value.
@@ -202,7 +210,7 @@ hash value.
| `orth` | The hash value of a word, or its unicode string. ~~Union[int, str]~~ |
| `vector` | The vector to set. ~~numpy.ndarray[ndim=1, dtype=float32]~~ |
-## Vocab.has_vector {#has_vector tag="method" new="2"}
+## Vocab.has_vector {id="has_vector",tag="method",version="2"}
Check whether a word has a vector. Returns `False` if no vectors are loaded.
Words can be looked up by string or hash value.
@@ -219,7 +227,7 @@ Words can be looked up by string or hash value.
| `orth` | The hash value of a word, or its unicode string. ~~Union[int, str]~~ |
| **RETURNS** | Whether the word has a vector. ~~bool~~ |
-## Vocab.to_disk {#to_disk tag="method" new="2"}
+## Vocab.to_disk {id="to_disk",tag="method",version="2"}
Save the current state to a directory.
@@ -235,7 +243,7 @@ Save the current state to a directory.
| _keyword-only_ | |
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
-## Vocab.from_disk {#from_disk tag="method" new="2"}
+## Vocab.from_disk {id="from_disk",tag="method",version="2"}
Loads state from a directory. Modifies the object in place and returns it.
@@ -253,7 +261,7 @@ Loads state from a directory. Modifies the object in place and returns it.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The modified `Vocab` object. ~~Vocab~~ |
-## Vocab.to_bytes {#to_bytes tag="method"}
+## Vocab.to_bytes {id="to_bytes",tag="method"}
Serialize the current state to a binary string.
@@ -269,7 +277,7 @@ Serialize the current state to a binary string.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The serialized form of the `Vocab` object. ~~Vocab~~ |
-## Vocab.from_bytes {#from_bytes tag="method"}
+## Vocab.from_bytes {id="from_bytes",tag="method"}
Load state from a binary string.
@@ -289,7 +297,7 @@ Load state from a binary string.
| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ |
| **RETURNS** | The `Vocab` object. ~~Vocab~~ |
-## Attributes {#attributes}
+## Attributes {id="attributes"}
> #### Example
>
@@ -300,16 +308,16 @@ Load state from a binary string.
> assert type(PERSON) == int
> ```
-| Name | Description |
-| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `strings` | A table managing the string-to-int mapping. ~~StringStore~~ |
-| `vectors` 2 | A table associating word IDs to word vectors. ~~Vectors~~ |
-| `vectors_length` | Number of dimensions for each word vector. ~~int~~ |
-| `lookups` | The available lookup tables in this vocab. ~~Lookups~~ |
-| `writing_system` 2.1 | A dict with information about the language's writing system. ~~Dict[str, Any]~~ |
-| `get_noun_chunks` 3.0 | A function that yields base noun phrases used for [`Doc.noun_chunks`](/ap/doc#noun_chunks). ~~Optional[Callable[[Union[Doc, Span], Iterator[Tuple[int, int, int]]]]]~~ |
+| Name | Description |
+| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `strings` | A table managing the string-to-int mapping. ~~StringStore~~ |
+| `vectors` | A table associating word IDs to word vectors. ~~Vectors~~ |
+| `vectors_length` | Number of dimensions for each word vector. ~~int~~ |
+| `lookups` | The available lookup tables in this vocab. ~~Lookups~~ |
+| `writing_system` | A dict with information about the language's writing system. ~~Dict[str, Any]~~ |
+| `get_noun_chunks` 3.0 | A function that yields base noun phrases used for [`Doc.noun_chunks`](/api/doc#noun_chunks). ~~Optional[Callable[[Union[Doc, Span], Iterator[Tuple[int, int, int]]]]]~~ |
-## Serialization fields {#serialization-fields}
+## Serialization fields {id="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
diff --git a/website/docs/images/displacy-dep-founded.html b/website/docs/images/displacy-dep-founded.html
deleted file mode 100644
index e22984ee1..000000000
--- a/website/docs/images/displacy-dep-founded.html
+++ /dev/null
@@ -1,58 +0,0 @@
-
diff --git a/website/docs/images/displacy-ent-custom.html b/website/docs/images/displacy-ent-custom.html
deleted file mode 100644
index 709c6f631..000000000
--- a/website/docs/images/displacy-ent-custom.html
+++ /dev/null
@@ -1,33 +0,0 @@
-
But
- Google
- ORGis starting from behind. The company made a late push into hardware, and
- Apple
- ORG’s Siri, available on iPhones, and
- Amazon
- ORG’s Alexa software, which runs on its Echo and Dot devices, have clear leads in consumer
- adoption.
- When
-
- Sebastian Thrun
- PERSON
-
- started working on self-driving cars at
-
- Google
- ORG
-
- in
-
- 2007
- DATE
-
- , few people outside of the company took him seriously.
-
diff --git a/website/docs/images/displacy-long2.html b/website/docs/images/displacy-long2.html
deleted file mode 100644
index abe18c42a..000000000
--- a/website/docs/images/displacy-long2.html
+++ /dev/null
@@ -1,84 +0,0 @@
-
diff --git a/website/docs/images/pipeline-design.svg b/website/docs/images/pipeline-design.svg
deleted file mode 100644
index 88ccdab99..000000000
--- a/website/docs/images/pipeline-design.svg
+++ /dev/null
@@ -1,49 +0,0 @@
-
diff --git a/website/docs/index.md b/website/docs/index.md
deleted file mode 100644
index 48e487d08..000000000
--- a/website/docs/index.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
----
-
-import Landing from 'widgets/landing.js'
-
-
diff --git a/website/docs/models/index.md b/website/docs/models/index.mdx
similarity index 68%
rename from website/docs/models/index.md
rename to website/docs/models/index.mdx
index 92d1b0172..371e4460f 100644
--- a/website/docs/models/index.md
+++ b/website/docs/models/index.mdx
@@ -7,7 +7,7 @@ menu:
- ['Pipeline Design', 'design']
---
-
+{/* TODO: include interactive demo */}
### Quickstart {hidden="true"}
@@ -16,11 +16,9 @@ menu:
> For more details on how to use trained pipelines with spaCy, see the
> [usage guide](/usage/models).
-import QuickstartModels from 'widgets/quickstart-models.js'
-
-## Package naming conventions {#conventions}
+## Package naming conventions {id="conventions"}
In general, spaCy expects all pipeline packages to follow the naming convention
of `[lang]\_[name]`. For spaCy's pipelines, we also chose to divide the name
@@ -30,16 +28,22 @@ into three components:
tagging, parsing, lemmatization and named entity recognition, or `dep` for
only tagging, parsing and lemmatization).
2. **Genre:** Type of text the pipeline is trained on, e.g. `web` or `news`.
-3. **Size:** Package size indicator, `sm`, `md`, `lg` or `trf` (`sm`: no word
- vectors, `md`: reduced word vector table with 20k unique vectors for ~500k
- words, `lg`: large word vector table with ~500k entries, `trf`: transformer
- pipeline without static word vectors)
+3. **Size:** Package size indicator, `sm`, `md`, `lg` or `trf`.
+
+ `sm` and `trf` pipelines have no static word vectors.
+
+ For pipelines with default vectors, `md` has a reduced word vector table with
+ 20k unique vectors for ~500k words and `lg` has a large word vector table
+ with ~500k entries.
+
+ For pipelines with floret vectors, `md` vector tables have 50k entries and
+ `lg` vector tables have 200k entries.
For example, [`en_core_web_sm`](/models/en#en_core_web_sm) is a small English
pipeline trained on written web text (blogs, news, comments), that includes
vocabulary, syntax and entities.
-### Package versioning {#model-versioning}
+### Package versioning {id="model-versioning"}
Additionally, the pipeline package versioning reflects both the compatibility
with spaCy, as well as the model version. A package version `a.b.c` translates
@@ -56,7 +60,7 @@ For a detailed compatibility overview, see the
This is also the source of spaCy's internal compatibility check, performed when
you run the [`download`](/api/cli#download) command.
-## Trained pipeline design {#design}
+## Trained pipeline design {id="design"}
The spaCy v3 trained pipelines are designed to be efficient and configurable.
For example, multiple components can share a common "token-to-vector" model and
@@ -83,33 +87,56 @@ Main changes from spaCy v2 models:
- The lemmatizer tables and processing move from the vocab and tagger to a
separate `lemmatizer` component.
-### CNN/CPU pipeline design {#design-cnn}
+### CNN/CPU pipeline design {id="design-cnn"}
-
+
In the `sm`/`md`/`lg` models:
- The `tagger`, `morphologizer` and `parser` components listen to the `tok2vec`
- component.
+ component. If the lemmatizer is trainable (v3.3+), `lemmatizer` also listens
+ to `tok2vec`.
- The `attribute_ruler` maps `token.tag` to `token.pos` if there is no
`morphologizer`. The `attribute_ruler` additionally makes sure whitespace is
tagged consistently and copies `token.pos` to `token.tag` if there is no
tagger. For English, the attribute ruler can improve its mapping from
`token.tag` to `token.pos` if dependency parses from a `parser` are present,
but the parser is not required.
-- The `lemmatizer` component for many languages (Catalan, Dutch, English,
- French, Greek, Italian Macedonian, Norwegian, Polish and Spanish) requires
- `token.pos` annotation from either `tagger`+`attribute_ruler` or
- `morphologizer`.
+- The `lemmatizer` component for many languages requires `token.pos` annotation
+ from either `tagger`+`attribute_ruler` or `morphologizer`.
- The `ner` component is independent with its own internal tok2vec layer.
-### Transformer pipeline design {#design-trf}
+#### CNN/CPU pipelines with floret vectors
+
+The Finnish, Korean and Swedish `md` and `lg` pipelines use
+[floret vectors](/usage/v3-2#vectors) instead of default vectors. If you're
+running a trained pipeline on texts and working with [`Doc`](/api/doc) objects,
+you shouldn't notice any difference with floret vectors. With floret vectors no
+tokens are out-of-vocabulary, so [`Token.is_oov`](/api/token#attributes) will
+return `False` for all tokens.
+
+If you access vectors directly for similarity comparisons, there are a few
+differences because floret vectors don't include a fixed word list like the
+vector keys for default vectors.
+
+- If your workflow iterates over the vector keys, you need to use an external
+ word list instead:
+
+ ```diff
+ - lexemes = [nlp.vocab[orth] for orth in nlp.vocab.vectors]
+ + lexemes = [nlp.vocab[word] for word in external_word_list]
+ ```
+
+- [`Vectors.most_similar`](/api/vectors#most_similar) is not supported because
+ there's no fixed list of vectors to compare your vectors to.
+
+### Transformer pipeline design {id="design-trf"}
In the transformer (`trf`) models, the `tagger`, `parser` and `ner` (if present)
all listen to the `transformer` component. The `attribute_ruler` and
`lemmatizer` have the same configuration as in the CNN models.
-### Modifying the default pipeline {#design-modify}
+### Modifying the default pipeline {id="design-modify"}
For faster processing, you may only want to run a subset of the components in a
trained pipeline. The `disable` and `exclude` arguments to
@@ -133,10 +160,14 @@ nlp = spacy.load("en_core_web_trf", disable=["tagger", "attribute_ruler", "lemma
-The lemmatizer depends on `tagger`+`attribute_ruler` or `morphologizer` for
-Catalan, Dutch, English, French, Greek, Italian, Macedonian, Norwegian, Polish
-and Spanish. If you disable any of these components, you'll see lemmatizer
-warnings unless the lemmatizer is also disabled.
+The lemmatizer depends on `tagger`+`attribute_ruler` or `morphologizer` for a
+number of languages. If you disable any of these components, you'll see
+lemmatizer warnings unless the lemmatizer is also disabled.
+
+**v3.3**: Catalan, English, French, Russian and Spanish
+
+**v3.0-v3.2**: Catalan, Dutch, English, French, Greek, Italian, Macedonian,
+Norwegian, Polish, Russian and Spanish
@@ -154,10 +185,34 @@ nlp.enable_pipe("senter")
The `senter` component is ~10× faster than the parser and more accurate
than the rule-based `sentencizer`.
+#### Switch from trainable lemmatizer to default lemmatizer
+
+Since v3.3, a number of pipelines use a trainable lemmatizer. You can check
+whether the lemmatizer is trainable:
+
+```python
+nlp = spacy.load("de_core_web_sm")
+assert nlp.get_pipe("lemmatizer").is_trainable
+```
+
+If you'd like to switch to a non-trainable lemmatizer that's similar to v3.2 or
+earlier, you can replace the trainable lemmatizer with the default non-trainable
+lemmatizer:
+
+```python
+# Requirements: pip install spacy-lookups-data
+nlp = spacy.load("de_core_web_sm")
+# Remove existing lemmatizer
+nlp.remove_pipe("lemmatizer")
+# Add non-trainable lemmatizer from language defaults
+# and load lemmatizer tables from spacy-lookups-data
+nlp.add_pipe("lemmatizer").initialize()
+```
+
#### Switch from rule-based to lookup lemmatization
For the Dutch, English, French, Greek, Macedonian, Norwegian and Spanish
-pipelines, you can switch from the default rule-based lemmatizer to a lookup
+pipelines, you can swap out a trainable or rule-based lemmatizer for a lookup
lemmatizer:
```python
diff --git a/website/docs/styleguide.md b/website/docs/styleguide.md
deleted file mode 100644
index ed6f9d99b..000000000
--- a/website/docs/styleguide.md
+++ /dev/null
@@ -1,30 +0,0 @@
----
-title: Styleguide
-section: styleguide
-search_exclude: true
-menu:
- - ['Logo', 'logo']
- - ['Colors', 'colors']
- - ['Typography', 'typography']
- - ['Elements', 'elements']
- - ['Components', 'components']
- - ['Setup & Installation', 'setup']
- - ['Markdown Reference', 'markdown']
- - ['Project Structure', 'structure']
- - ['Editorial', 'editorial']
-sidebar:
- - label: Styleguide
- items:
- - text: ''
- url: '/styleguide'
- - label: Resources
- items:
- - text: Website Source
- url: https://github.com/explosion/spacy/tree/master/website
- - text: Contributing Guide
- url: https://github.com/explosion/spaCy/blob/master/CONTRIBUTING.md
----
-
-import Readme from 'README.md'
-
-
diff --git a/website/docs/styleguide.mdx b/website/docs/styleguide.mdx
new file mode 100644
index 000000000..276137aab
--- /dev/null
+++ b/website/docs/styleguide.mdx
@@ -0,0 +1,615 @@
+---
+title: Styleguide
+section: styleguide
+search_exclude: true
+menu:
+ - ['Logo', 'logo']
+ - ['Colors', 'colors']
+ - ['Typography', 'typography']
+ - ['Elements', 'elements']
+ - ['Components', 'components']
+ - ['Markdown Reference', 'markdown']
+ - ['Editorial', 'editorial']
+sidebar:
+ - label: Styleguide
+ items:
+ - text: ''
+ url: '/styleguide'
+ - label: Resources
+ items:
+ - text: Website Source
+ url: https://github.com/explosion/spacy/tree/master/website
+ - text: Contributing Guide
+ url: https://github.com/explosion/spaCy/blob/master/CONTRIBUTING.md
+---
+
+The [spacy.io](https://spacy.io) website is implemented using
+[Gatsby](https://www.gatsbyjs.org) with
+[Remark](https://github.com/remarkjs/remark) and [MDX](https://mdxjs.com/). This
+allows authoring content in **straightforward Markdown** without the usual
+limitations. Standard elements can be overwritten with powerful
+[React](http://reactjs.org/) components and wherever Markdown syntax isn't
+enough, JSX components can be used.
+
+> #### Contributing to the site
+>
+> The docs can always use another example or more detail, and they should always
+> be up to date and not misleading. We always appreciate a
+> [pull request](https://github.com/explosion/spaCy/pulls). To quickly find the
+> correct file to edit, simply click on the "Suggest edits" button at the bottom
+> of a page.
+>
+> For more details on editing the site locally, see the installation
+> instructions and markdown reference below.
+
+## Logo {id="logo",source="website/src/images/logo.svg"}
+
+If you would like to use the spaCy logo on your site, please get in touch and
+ask us first. However, if you want to show support and tell others that your
+project is using spaCy, you can grab one of our
+[spaCy badges](/usage/spacy-101#faq-project-with-spacy).
+
+
+
+## Colors {id="colors"}
+
+
+
+### Patterns
+
+
+
+## Typography {id="typography"}
+
+> #### Markdown
+>
+> ```markdown
+> ## Headline 2
+>
+> ## Headline 2 {id="some_id"}
+>
+> ## Headline 2 {id="some_id" tag="method"}
+> ```
+>
+> #### JSX
+>
+> ```jsx
+>
Headline 2
+>
Headline 2
+>
Headline 2
+> ```
+
+Headlines are set in
+[HK Grotesk](http://cargocollective.com/hanken/HK-Grotesk-Open-Source-Font) by
+Hanken Design. All other body text and code uses the best-matching default
+system font to provide a "native" reading experience. All code uses the
+[JetBrains Mono](https://www.jetbrains.com/lp/mono/) typeface by JetBrains.
+
+
+
+Level 2 headings are automatically wrapped in `` elements at compile
+time, using a custom
+[Markdown transformer](https://github.com/explosion/spaCy/tree/master/website/plugins/remark-wrap-section.js).
+This makes it easier to highlight the section that's currently in the viewpoint
+in the sidebar menu.
+
+
+
+
+
Headline 2
+
Headline 3
+
Headline 4
+
Headline 5
+
+
+
+---
+
+The following optional attributes can be set on the headline to modify it. For
+example, to add a tag for the documented type or mark features that have been
+introduced in a specific version or require statistical models to be loaded.
+Tags are also available as standalone `` components.
+
+| Argument | Example | Result |
+| --------- | -------------------------- | ----------------------------------------- |
+| `tag` | `{tag="method"}` | method |
+| `version` | `{version="3"}` | 3 |
+| `model` | `{model="tagger, parser"}` | tagger, parser |
+| `hidden` | `{hidden="true"}` | |
+
+## Elements {id="elements"}
+
+### Links {id="links"}
+
+> #### Markdown
+>
+> ```markdown
+> [I am a link](https://spacy.io)
+> ```
+>
+> #### JSX
+>
+> ```jsx
+> I am a link
+> ```
+
+Special link styles are used depending on the link URL.
+
+- [I am a regular external link](https://explosion.ai)
+- [I am a link to the documentation](/api/doc)
+- [I am a link to an architecture](/api/architectures#HashEmbedCNN)
+- [I am a link to a model](/models/en#en_core_web_sm)
+- [I am a link to GitHub](https://github.com/explosion/spaCy)
+
+### Abbreviations {id="abbr"}
+
+> #### JSX
+>
+> ```jsx
+> Abbreviation
+> ```
+
+Some text with an abbreviation. On small
+screens, I collapse and the explanation text is displayed next to the
+abbreviation.
+
+### Tags {id="tags"}
+
+> ```jsx
+> method
+> 4
+> tagger, parser
+> ```
+
+Tags can be used together with headlines, or next to properties across the
+documentation, and combined with tooltips to provide additional information. An
+optional `variant` argument can be used for special tags. `variant="new"` makes
+the tag take a version number to mark new features. Using the component,
+visibility of this tag can later be toggled once the feature isn't considered
+new anymore. Setting `variant="model"` takes a description of model capabilities
+and can be used to mark features that require a respective model to be
+installed.
+
+
+ method
+ 4
+ tagger, parser
+
+
+### Buttons {id="buttons"}
+
+> ```jsx
+>
+>
+> ```
+
+Link buttons come in two variants, `primary` and `secondary` and two sizes, with
+an optional `large` size modifier. Since they're mostly used as enhanced links,
+the buttons are implemented as styled links instead of native button elements.
+
+
+> ```
+
+Tables are used to present data and API documentation. Certain keywords can be
+used to mark a footer row with a distinct style, for example to visualize the
+return values of a documented function.
+
+| Header 1 | Header 2 | Header 3 | Header 4 |
+| ----------- | -------- | :------: | -------: |
+| Column 1 | Column 2 | Column 3 | Column 4 |
+| Column 1 | Column 2 | Column 3 | Column 4 |
+| Column 1 | Column 2 | Column 3 | Column 4 |
+| Column 1 | Column 2 | Column 3 | Column 4 |
+| **RETURNS** | Column 2 | Column 3 | Column 4 |
+
+Tables also support optional "divider" rows that are typically used to denote
+keyword-only arguments in API documentation. To turn a row into a dividing
+headline, it should only include content in its first cell, and its value should
+be italicized:
+
+> #### Markdown
+>
+> ```markdown
+> | Header 1 | Header 2 | Header 3 |
+> | -------- | -------- | -------- |
+> | Column 1 | Column 2 | Column 3 |
+> | _Hello_ | | |
+> | Column 1 | Column 2 | Column 3 |
+> ```
+
+| Header 1 | Header 2 | Header 3 |
+| -------- | -------- | -------- |
+| Column 1 | Column 2 | Column 3 |
+| _Hello_ | | |
+| Column 1 | Column 2 | Column 3 |
+
+### Type Annotations {id="type-annotations"}
+
+> #### Markdown
+>
+> ```markdown
+> ~~Model[List[Doc], Floats2d]~~
+> ```
+>
+> #### JSX
+>
+> ```markup
+> Model[List[Doc], Floats2d]
+> ```
+
+Type annotations are special inline code blocks are used to describe Python
+types in the [type hints](https://docs.python.org/3/library/typing.html) format.
+The special component will split the type, apply syntax highlighting and link
+all types that specify links in `meta/type-annotations.json`. Types can link to
+internal or external documentation pages. To make it easy to represent the type
+annotations in Markdown, the rendering "hijacks" the `~~` tags that would
+typically be converted to a `` element – but in this case, text surrounded
+by `~~` becomes a type annotation.
+
+- ~~Dict[str, List[Union[Doc, Span]]]~~
+- ~~Model[List[Doc], List[numpy.ndarray]]~~
+
+Type annotations support a special visual style in tables and will render as a
+separate row, under the cell text. This allows the API docs to display complex
+types without taking up too much space in the cell. The type annotation should
+always be the **last element** in the row.
+
+> #### Markdown
+>
+> ```markdown
+> | Header 1 | Header 2 |
+> | -------- | ---------------------- |
+> | Column 1 | Column 2 ~~List[Doc]~~ |
+> ```
+
+| Name | Description |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `vocab` | The shared vocabulary. ~~Vocab~~ |
+| `model` | The Thinc [`Model`](https://thinc.ai/docs/api-model) wrapping the transformer. ~~Model[List[Doc], FullTransformerBatch]~~ |
+| `set_extra_annotations` | Function that takes a batch of `Doc` objects and transformer outputs and can set additional annotations on the `Doc`. ~~Callable[[List[Doc], FullTransformerBatch], None]~~ |
+
+### List {id="list"}
+
+> #### Markdown
+>
+> ```markdown
+> 1. One
+> 2. Two
+> ```
+>
+> #### JSX
+>
+> ```markup
+>
+>
One
+>
Two
+>
+> ```
+
+Lists are available as bulleted and numbered. Markdown lists are transformed
+automatically.
+
+- I am a bulleted list
+- I have nice bullets
+- Lorem ipsum dolor
+- consectetur adipiscing elit
+
+1. I am an ordered list
+2. I have nice numbers
+3. Lorem ipsum dolor
+4. consectetur adipiscing elit
+
+### Aside {id="aside"}
+
+> #### Markdown
+>
+> ```markdown
+> > #### Aside title
+> >
+> > This is aside text.
+> ```
+>
+> #### JSX
+>
+> ```jsx
+>
+> ```
+
+Asides can be used to display additional notes and content in the right-hand
+column. Asides can contain text, code and other elements if needed. Visually,
+asides are moved to the side on the X-axis, and displayed at the same level they
+were inserted. On small screens, they collapse and are rendered in their
+original position, in between the text.
+
+To make them easier to use in Markdown, paragraphs formatted as blockquotes will
+turn into asides by default. Level 4 headlines (with a leading `####`) will
+become aside titles.
+
+### Code Block {id="code-block"}
+
+> #### Markdown
+>
+> ````markdown
+> ```python
+> ### This is a title
+> import spacy
+> ```
+> ````
+>
+> #### JSX
+>
+> ```jsx
+>
+> import spacy
+>
+> ```
+
+Code blocks use the [Prism](http://prismjs.com/) syntax highlighter with a
+custom theme. The language can be set individually on each block, and defaults
+to raw text with no highlighting. An optional label can be added as the first
+line with the prefix `####` (Python-like) and `///` (JavaScript-like). the
+indented block as plain text and preserve whitespace.
+
+```python {title="Using spaCy"}
+import spacy
+nlp = spacy.load("en_core_web_sm")
+doc = nlp("This is a sentence.")
+for token in doc:
+ print(token.text, token.pos_)
+```
+
+Code blocks and also specify an optional range of line numbers to highlight by
+adding `{highlight="..."}` to the headline. Acceptable ranges are spans like
+`5-7`, but also `5-7,10` or `5-7,10,13-14`.
+
+> #### Markdown
+>
+> ````markdown
+> ```python
+> ### This is a title {highlight="1-2"}
+> import spacy
+> nlp = spacy.load("en_core_web_sm")
+> ```
+> ````
+
+```python {title="Using the matcher",highlight="5-7"}
+import spacy
+from spacy.matcher import Matcher
+
+nlp = spacy.load('en_core_web_sm')
+matcher = Matcher(nlp.vocab)
+pattern = [{"LOWER": "hello"}, {"IS_PUNCT": True}, {"LOWER": "world"}]
+matcher.add("HelloWorld", None, pattern)
+doc = nlp("Hello, world! Hello world!")
+matches = matcher(doc)
+```
+
+Adding `{executable="true"}` to the title turns the code into an executable
+block, powered by [Binder](https://mybinder.org) and
+[Juniper](https://github.com/ines/juniper). If JavaScript is disabled, the
+interactive widget defaults to a regular code block.
+
+> #### Markdown
+>
+> ````markdown
+> ```python
+> ### {executable="true"}
+> import spacy
+> nlp = spacy.load("en_core_web_sm")
+> ```
+> ````
+
+```python {executable="true"}
+import spacy
+nlp = spacy.load("en_core_web_sm")
+doc = nlp("This is a sentence.")
+for token in doc:
+ print(token.text, token.pos_)
+```
+
+If a code block only contains a URL to a GitHub file, the raw file contents are
+embedded automatically and syntax highlighting is applied. The link to the
+original file is shown at the top of the widget.
+
+> #### Markdown
+>
+> ````markdown
+> ```python
+> https://github.com/...
+> ```
+> ````
+>
+> #### JSX
+>
+> ```jsx
+>
+> ```
+
+```python
+https://github.com/explosion/spaCy/tree/master/spacy/language.py
+```
+
+### Infobox {id="infobox"}
+
+> #### JSX
+>
+> ```jsx
+> Regular infobox
+> This is a warning.
+> This is dangerous.
+> ```
+
+Infoboxes can be used to add notes, updates, warnings or additional information
+to a page or section. Semantically, they're implemented and interpreted as an
+`aside` element. Infoboxes can take an optional `title` argument, as well as an
+optional `variant` (either `"warning"` or `"danger"`).
+
+
+
+If needed, an infobox can contain regular text, `inline code`, lists and other
+blocks.
+
+
+
+
+
+If needed, an infobox can contain regular text, `inline code`, lists and other
+blocks.
+
+
+
+
+
+If needed, an infobox can contain regular text, `inline code`, lists and other
+blocks.
+
+
+
+### Accordion {id="accordion"}
+
+> #### JSX
+>
+> ```jsx
+>
+> Accordion content goes here.
+>
+> ```
+
+Accordions are collapsible sections that are mostly used for lengthy tables,
+like the tag and label annotation schemes for different languages. They all need
+to be presented – but chances are the user doesn't actually care about _all_ of
+them, especially not at the same time. So it's fairly reasonable to hide them
+begin a click. This particular implementation was inspired by the amazing
+[Inclusive Components blog](https://inclusive-components.design/collapsible-sections/).
+
+
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque enim ante,
+pretium a orci eget, varius dignissim augue. Nam eu dictum mauris, id tincidunt
+nisi. Integer commodo pellentesque tincidunt. Nam at turpis finibus tortor
+gravida sodales tincidunt sit amet est. Nullam euismod arcu in tortor auctor,
+sit amet dignissim justo congue.
+
+
+
+## Markdown reference {id="markdown"}
+
+All page content and page meta lives in the `.mdx` files in the `/docs`
+directory. The frontmatter block at the top of each file defines the page title
+and other settings like the sidebar menu.
+
+````markdown
+---
+title: Page title
+---
+
+## Headline starting a section {id="some_id"}
+
+This is a regular paragraph with a [link](https://spacy.io) and **bold text**.
+
+> #### This is an aside title
+>
+> This is aside text.
+
+### Subheadline
+
+| Header 1 | Header 2 |
+| -------- | -------- |
+| Column 1 | Column 2 |
+
+```python {title="Code block title",highlight="2-3"}
+import spacy
+nlp = spacy.load("en_core_web_sm")
+doc = nlp("Hello world")
+```
+
+
+
+This is content in the infobox.
+
+
+````
+
+In addition to the native markdown elements, you can use the components
+[``][infobox], [``][accordion], [``][abbr] and
+[``][tag] via their JSX syntax.
+
+[infobox]: https://spacy.io/styleguide#infobox
+[accordion]: https://spacy.io/styleguide#accordion
+[abbr]: https://spacy.io/styleguide#abbr
+[tag]: https://spacy.io/styleguide#tag
+
+## Editorial {id="editorial"}
+
+- "spaCy" should always be spelled with a lowercase "s" and a capital "C",
+ unless it specifically refers to the Python package or Python import `spacy`
+ (in which case it should be formatted as code).
+ - ✅ spaCy is a library for advanced NLP in Python.
+ - ❌ Spacy is a library for advanced NLP in Python.
+ - ✅ First, you need to install the `spacy` package from pip.
+- Mentions of code, like function names, classes, variable names etc. in inline
+ text should be formatted as `code`.
+ - ✅ "Calling the `nlp` object on a text returns a `Doc`."
+- Objects that have pages in the [API docs](/api) should be linked – for
+ example, [`Doc`](/api/doc) or [`Language.to_disk`](/api/language#to_disk). The
+ mentions should still be formatted as code within the link. Links pointing to
+ the API docs will automatically receive a little icon. However, if a paragraph
+ includes many references to the API, the links can easily get messy. In that
+ case, we typically only link the first mention of an object and not any
+ subsequent ones.
+ - ✅ The [`Span`](/api/span) and [`Token`](/api/token) objects are views of a
+ [`Doc`](/api/doc). [`Span.as_doc`](/api/span#as_doc) creates a `Doc` object
+ from a `Span`.
+ - ❌ The [`Span`](/api/span) and [`Token`](/api/token) objects are views of a
+ [`Doc`](/api/doc). [`Span.as_doc`](/api/span#as_doc) creates a
+ [`Doc`](/api/doc) object from a [`Span`](/api/span).
+- Other things we format as code are: references to trained pipeline packages
+ like `en_core_web_sm` or file names like `code.py` or `meta.json`.
+ - ✅ After training, the `config.cfg` is saved to disk.
+- [Type annotations](#type-annotations) are a special type of code formatting,
+ expressed by wrapping the text in `~~` instead of backticks. The result looks
+ like this: ~~List[Doc]~~. All references to known types will be linked
+ automatically.
+ - ✅ The model has the input type ~~List[Doc]~~ and it outputs a
+ ~~List[Array2d]~~.
+- We try to keep links meaningful but short.
+ - ✅ For details, see the usage guide on
+ [training with custom code](/usage/training#custom-code).
+ - ❌ For details, see
+ [the usage guide on training with custom code](/usage/training#custom-code).
+ - ❌ For details, see the usage guide on training with custom code
+ [here](/usage/training#custom-code).
diff --git a/website/docs/usage/101/_architecture.md b/website/docs/usage/101/_architecture.mdx
similarity index 90%
rename from website/docs/usage/101/_architecture.md
rename to website/docs/usage/101/_architecture.mdx
index 8fb452895..2a63a3741 100644
--- a/website/docs/usage/101/_architecture.md
+++ b/website/docs/usage/101/_architecture.mdx
@@ -14,9 +14,9 @@ of the pipeline. The `Language` object coordinates these components. It takes
raw text and sends it through the pipeline, returning an **annotated document**.
It also orchestrates training and serialization.
-
+
-### Container objects {#architecture-containers}
+### Container objects {id="architecture-containers"}
| Name | Description |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -29,7 +29,7 @@ It also orchestrates training and serialization.
| [`SpanGroup`](/api/spangroup) | A named collection of spans belonging to a `Doc`. |
| [`Token`](/api/token) | An individual token — i.e. a word, punctuation symbol, whitespace, etc. |
-### Processing pipeline {#architecture-pipeline}
+### Processing pipeline {id="architecture-pipeline"}
The processing pipeline consists of one or more **pipeline components** that are
called on the `Doc` in order. The tokenizer runs before the components. Pipeline
@@ -39,16 +39,17 @@ rule-based modifications to the `Doc`. spaCy provides a range of built-in
components for different language processing tasks and also allows adding
[custom components](/usage/processing-pipelines#custom-components).
-
+
| Name | Description |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------- |
| [`AttributeRuler`](/api/attributeruler) | Set token attributes using matcher rules. |
| [`DependencyParser`](/api/dependencyparser) | Predict syntactic dependencies. |
+| [`EditTreeLemmatizer`](/api/edittreelemmatizer) | Predict base forms of words. |
| [`EntityLinker`](/api/entitylinker) | Disambiguate named entities to nodes in a knowledge base. |
| [`EntityRecognizer`](/api/entityrecognizer) | Predict named entities, e.g. persons or products. |
| [`EntityRuler`](/api/entityruler) | Add entity spans to the `Doc` using token-based rules or exact phrase matches. |
-| [`Lemmatizer`](/api/lemmatizer) | Determine the base forms of words. |
+| [`Lemmatizer`](/api/lemmatizer) | Determine the base forms of words using rules and lookups. |
| [`Morphologizer`](/api/morphologizer) | Predict morphological features and coarse-grained part-of-speech tags. |
| [`SentenceRecognizer`](/api/sentencerecognizer) | Predict sentence boundaries. |
| [`Sentencizer`](/api/sentencizer) | Implement rule-based sentence boundary detection that doesn't require the dependency parse. |
@@ -60,7 +61,7 @@ components for different language processing tasks and also allows adding
| [`Transformer`](/api/transformer) | Use a transformer model and set its outputs. |
| [Other functions](/api/pipeline-functions) | Automatically apply something to the `Doc`, e.g. to merge spans of tokens. |
-### Matchers {#architecture-matchers}
+### Matchers {id="architecture-matchers"}
Matchers help you find and extract information from [`Doc`](/api/doc) objects
based on match patterns describing the sequences you're looking for. A matcher
@@ -72,12 +73,14 @@ operates on a `Doc` and gives you access to the matched tokens **in context**.
| [`Matcher`](/api/matcher) | Match sequences of tokens, based on pattern rules, similar to regular expressions. |
| [`PhraseMatcher`](/api/phrasematcher) | Match sequences of tokens based on phrases. |
-### Other classes {#architecture-other}
+### Other classes {id="architecture-other"}
| Name | Description |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| [`Corpus`](/api/corpus) | Class for managing annotated corpora for training and evaluation data. |
-| [`KnowledgeBase`](/api/kb) | Storage for entities and aliases of a knowledge base for entity linking. |
+| [`KnowledgeBase`](/api/kb) | Abstract base class for storage and retrieval of data for entity linking. |
+| [`InMemoryLookupKB`](/api/inmemorylookupkb) | Implementation of `KnowledgeBase` storing all data in memory. |
+| [`Candidate`](/api/kb#candidate) | Object associating a textual mention with a specific entity contained in a `KnowledgeBase`. |
| [`Lookups`](/api/lookups) | Container for convenient access to large lookup tables and dictionaries. |
| [`MorphAnalysis`](/api/morphology#morphanalysis) | A morphological analysis. |
| [`Morphology`](/api/morphology) | Store morphological analyses and map them to and from hash values. |
diff --git a/website/docs/usage/101/_language-data.md b/website/docs/usage/101/_language-data.mdx
similarity index 100%
rename from website/docs/usage/101/_language-data.md
rename to website/docs/usage/101/_language-data.mdx
diff --git a/website/docs/usage/101/_named-entities.md b/website/docs/usage/101/_named-entities.mdx
similarity index 75%
rename from website/docs/usage/101/_named-entities.md
rename to website/docs/usage/101/_named-entities.mdx
index 2abc45cbd..9ae4134d8 100644
--- a/website/docs/usage/101/_named-entities.md
+++ b/website/docs/usage/101/_named-entities.mdx
@@ -1,14 +1,13 @@
A named entity is a "real-world object" that's assigned a name – for example, a
person, a country, a product or a book title. spaCy can **recognize various
-types of named entities in a document, by asking the model for a
-prediction**. Because models are statistical and strongly depend on the
-examples they were trained on, this doesn't always work _perfectly_ and might
-need some tuning later, depending on your use case.
+types of named entities in a document, by asking the model for a prediction**.
+Because models are statistical and strongly depend on the examples they were
+trained on, this doesn't always work _perfectly_ and might need some tuning
+later, depending on your use case.
Named entities are available as the `ents` property of a `Doc`:
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.load("en_core_web_sm")
@@ -32,7 +31,8 @@ for ent in doc.ents:
Using spaCy's built-in [displaCy visualizer](/usage/visualizers), here's what
our example sentence and its named entities look like:
-import DisplaCyEntHtml from 'images/displacy-ent1.html'; import { Iframe } from
-'components/embed'
-
-
+
diff --git a/website/docs/usage/101/_pipelines.md b/website/docs/usage/101/_pipelines.mdx
similarity index 98%
rename from website/docs/usage/101/_pipelines.md
rename to website/docs/usage/101/_pipelines.mdx
index f43219f41..315291762 100644
--- a/website/docs/usage/101/_pipelines.md
+++ b/website/docs/usage/101/_pipelines.mdx
@@ -5,7 +5,7 @@ referred to as the **processing pipeline**. The pipeline used by the
and an entity recognizer. Each pipeline component returns the processed `Doc`,
which is then passed on to the next component.
-
+
> - **Name**: ID of the pipeline component.
> - **Component:** spaCy's implementation of the component.
@@ -35,8 +35,6 @@ the [config](/usage/training#config):
pipeline = ["tok2vec", "tagger", "parser", "ner"]
```
-import Accordion from 'components/accordion.js'
-
The statistical components like the tagger or parser are typically independent
diff --git a/website/docs/usage/101/_pos-deps.md b/website/docs/usage/101/_pos-deps.mdx
similarity index 92%
rename from website/docs/usage/101/_pos-deps.md
rename to website/docs/usage/101/_pos-deps.mdx
index 93ad0961a..bedb6ce2c 100644
--- a/website/docs/usage/101/_pos-deps.md
+++ b/website/docs/usage/101/_pos-deps.mdx
@@ -11,8 +11,7 @@ Linguistic annotations are available as
efficiency. So to get the readable string representation of an attribute, we
need to add an underscore `_` to its name:
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.load("en_core_web_sm")
@@ -57,7 +56,8 @@ for token in doc:
Using spaCy's built-in [displaCy visualizer](/usage/visualizers), here's what
our example sentence and its dependencies look like:
-import DisplaCyLongHtml from 'images/displacy-long.html'; import { Iframe } from
-'components/embed'
-
-
+
diff --git a/website/docs/usage/101/_serialization.md b/website/docs/usage/101/_serialization.mdx
similarity index 100%
rename from website/docs/usage/101/_serialization.md
rename to website/docs/usage/101/_serialization.mdx
diff --git a/website/docs/usage/101/_tokenization.md b/website/docs/usage/101/_tokenization.mdx
similarity index 95%
rename from website/docs/usage/101/_tokenization.md
rename to website/docs/usage/101/_tokenization.mdx
index b82150f1a..4315ab43b 100644
--- a/website/docs/usage/101/_tokenization.md
+++ b/website/docs/usage/101/_tokenization.mdx
@@ -4,8 +4,7 @@ language. For example, punctuation at the end of a sentence should be split off
– whereas "U.K." should remain one token. Each `Doc` consists of individual
tokens, and we can iterate over them:
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.load("en_core_web_sm")
@@ -41,7 +40,7 @@ marks.
> - **Suffix:** Character(s) at the end, e.g. `km`, `)`, `”`, `!`.
> - **Infix:** Character(s) in between, e.g. `-`, `--`, `/`, `…`.
-
+
While punctuation rules are usually pretty general, tokenizer exceptions
strongly depend on the specifics of the individual language. This is why each
diff --git a/website/docs/usage/101/_training.md b/website/docs/usage/101/_training.mdx
similarity index 91%
rename from website/docs/usage/101/_training.md
rename to website/docs/usage/101/_training.mdx
index 4218c1b5a..6587ea339 100644
--- a/website/docs/usage/101/_training.md
+++ b/website/docs/usage/101/_training.mdx
@@ -10,9 +10,9 @@ any other information.
Training is an iterative process in which the model's predictions are compared
against the reference annotations in order to estimate the **gradient of the
loss**. The gradient of the loss is then used to calculate the gradient of the
-weights through [backpropagation](https://thinc.ai/docs/backprop101). The gradients
-indicate how the weight values should be changed so that the model's predictions
-become more similar to the reference labels over time.
+weights through [backpropagation](https://thinc.ai/docs/backprop101). The
+gradients indicate how the weight values should be changed so that the model's
+predictions become more similar to the reference labels over time.
> - **Training data:** Examples and their annotations.
> - **Text:** The input text the model should predict a label for.
@@ -21,7 +21,7 @@ become more similar to the reference labels over time.
> Minimising the gradient of the weights should result in predictions that are
> closer to the reference labels on the training data.
-
+
When training a model, we don't just want it to memorize our examples – we want
it to come up with a theory that can be **generalized across unseen data**.
diff --git a/website/docs/usage/101/_vectors-similarity.md b/website/docs/usage/101/_vectors-similarity.mdx
similarity index 96%
rename from website/docs/usage/101/_vectors-similarity.md
rename to website/docs/usage/101/_vectors-similarity.mdx
index f05fedd7d..c27f777d8 100644
--- a/website/docs/usage/101/_vectors-similarity.md
+++ b/website/docs/usage/101/_vectors-similarity.mdx
@@ -1,12 +1,9 @@
-import Infobox from 'components/infobox'
-
Similarity is determined by comparing **word vectors** or "word embeddings",
multi-dimensional meaning representations of a word. Word vectors can be
generated using an algorithm like
[word2vec](https://en.wikipedia.org/wiki/Word2vec) and usually look like this:
-```python
-### banana.vector
+```python {title="banana.vector"}
array([2.02280000e-01, -7.66180009e-02, 3.70319992e-01,
3.28450017e-02, -4.19569999e-01, 7.20689967e-02,
-3.74760002e-01, 5.74599989e-02, -1.24009997e-02,
@@ -44,8 +41,7 @@ the [`Token.vector`](/api/token#vector) attribute.
default to an average of their token vectors. You can also check if a token has
a vector assigned, and get the L2 norm, which can be used to normalize vectors.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.load("en_core_web_md")
@@ -95,8 +91,7 @@ similarity.
> You should see that the similarity results are identical to the token
> similarity.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.load("en_core_web_md") # make sure to use larger package!
@@ -111,7 +106,7 @@ burgers = doc1[5]
print(french_fries, "<->", burgers, french_fries.similarity(burgers))
```
-### What to expect from similarity results {#similarity-expectations}
+### What to expect from similarity results {id="similarity-expectations"}
Computing similarity scores can be helpful in many situations, but it's also
important to maintain **realistic expectations** about what information it can
@@ -136,7 +131,10 @@ useful for your purpose. Here are some important considerations to keep in mind:
-[](https://github.com/explosion/sense2vec)
+
[`sense2vec`](https://github.com/explosion/sense2vec) is a library developed by
us that builds on top of spaCy and lets you train and query more interesting and
diff --git a/website/docs/usage/_benchmarks-models.md b/website/docs/usage/_benchmarks-models.mdx
similarity index 86%
rename from website/docs/usage/_benchmarks-models.md
rename to website/docs/usage/_benchmarks-models.mdx
index 5bf9e63ca..c85a1194e 100644
--- a/website/docs/usage/_benchmarks-models.md
+++ b/website/docs/usage/_benchmarks-models.mdx
@@ -1,5 +1,3 @@
-import { Help } from 'components/typography'; import Link from 'components/link'
-
| Pipeline | Parser | Tagger | NER |
@@ -8,7 +6,7 @@ import { Help } from 'components/typography'; import Link from 'components/link'
| [`en_core_web_lg`](/models/en#en_core_web_lg) (spaCy v3) | 92.0 | 97.4 | 85.5 |
| `en_core_web_lg` (spaCy v2) | 91.9 | 97.2 | 85.5 |
-
+
**Full pipeline accuracy** on the
[OntoNotes 5.0](https://catalog.ldc.upenn.edu/LDC2013T19) corpus (reported on
@@ -26,15 +24,15 @@ the development set).
| Stanza (StanfordNLP)1 | 88.8 | 92.1 |
| Flair2 | 89.7 | 93.1 |
-
+
**Named entity recognition accuracy** on the
[OntoNotes 5.0](https://catalog.ldc.upenn.edu/LDC2013T19) and
[CoNLL-2003](https://www.aclweb.org/anthology/W03-0419.pdf) corpora. See
[NLP-progress](http://nlpprogress.com/english/named_entity_recognition.html) for
more results. Project template:
-[`benchmarks/ner_conll03`](%%GITHUB_PROJECTS/benchmarks/ner_conll03). **1. **
-[Qi et al. (2020)](https://arxiv.org/pdf/2003.07082.pdf). **2. **
+[`benchmarks/ner_conll03`](%%GITHUB_PROJECTS/benchmarks/ner_conll03). **1.**
+[Qi et al. (2020)](https://arxiv.org/pdf/2003.07082.pdf). **2.**
[Akbik et al. (2018)](https://www.aclweb.org/anthology/C18-1139/).
diff --git a/website/docs/usage/embeddings-transformers.md b/website/docs/usage/embeddings-transformers.mdx
similarity index 92%
rename from website/docs/usage/embeddings-transformers.md
rename to website/docs/usage/embeddings-transformers.mdx
index 708cdd8bf..cf80822fb 100644
--- a/website/docs/usage/embeddings-transformers.md
+++ b/website/docs/usage/embeddings-transformers.mdx
@@ -74,7 +74,7 @@ of performance.
-## Shared embedding layers {#embedding-layers}
+## Shared embedding layers {id="embedding-layers"}
spaCy lets you share a single transformer or other token-to-vector ("tok2vec")
embedding layer between multiple components. You can even update the shared
@@ -85,7 +85,7 @@ difficult to swap components or retrain parts of the pipeline. Multi-task
learning can affect your accuracy (either positively or negatively), and may
require some retuning of your hyper-parameters.
-
+
| Shared | Independent |
| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
@@ -99,7 +99,7 @@ components by adding a [`Transformer`](/api/transformer) or
later in the pipeline can "connect" to it by including a **listener layer** like
[Tok2VecListener](/api/architectures#Tok2VecListener) within their model.
-
+
At the beginning of training, the [`Tok2Vec`](/api/tok2vec) component will grab
a reference to the relevant listener layers in the rest of your pipeline. When
@@ -113,7 +113,7 @@ transformer outputs to the
[`Doc._.trf_data`](/api/transformer#custom_attributes) extension attribute,
giving you access to them after the pipeline has finished running.
-### Example: Shared vs. independent config {#embedding-layers-config}
+### Example: Shared vs. independent config {id="embedding-layers-config"}
The [config system](/usage/training#config) lets you express model configuration
for both shared and independent embedding layers. The shared setup uses a single
@@ -123,8 +123,7 @@ the entity recognizer, use a
[Tok2VecListener](/api/architectures#Tok2VecListener) layer as their model's
`tok2vec` argument, which connects to the `tok2vec` component model.
-```ini
-### Shared {highlight="1-2,4-5,19-20"}
+```ini {title="Shared",highlight="1-2,4-5,19-20"}
[components.tok2vec]
factory = "tok2vec"
@@ -152,8 +151,7 @@ In the independent setup, the entity recognizer component defines its own
same. This makes them fully independent and doesn't require an upstream
[`Tok2Vec`](/api/tok2vec) component to be present in the pipeline.
-```ini
-### Independent {highlight="7-8"}
+```ini {title="Independent", highlight="7-8"}
[components.ner]
factory = "ner"
@@ -170,9 +168,9 @@ factory = "ner"
@architectures = "spacy.MaxoutWindowEncoder.v2"
```
-
+{/* TODO: Once rehearsal is tested, mention it here. */}
-## Using transformer models {#transformers}
+## Using transformer models {id="transformers"}
Transformers are a family of neural network architectures that compute **dense,
context-sensitive representations** for the tokens in your documents. Downstream
@@ -188,7 +186,7 @@ transformer models, but for practical purposes, you can simply think of them as
drop-in replacements that let you achieve **higher accuracy** in exchange for
**higher training and runtime costs**.
-### Setup and installation {#transformers-installation}
+### Setup and installation {id="transformers-installation"}
> #### System requirements
>
@@ -210,24 +208,22 @@ your package manager and CUDA version. If you skip this step, pip will install
PyTorch as a dependency below, but it may not find the best version for your
setup.
-```bash
-### Example: Install PyTorch 1.7.1 for CUDA 10.1 with pip
+```bash {title="Example: Install PyTorch 1.11.0 for CUDA 11.3 with pip"}
# See: https://pytorch.org/get-started/locally/
-$ pip install torch==1.7.1+cu101 torchvision==0.8.2+cu101 torchaudio==0.7.2 -f https://download.pytorch.org/whl/torch_stable.html
+$ pip install torch==1.11.0+cu113 torchvision==0.12.0+cu113 torchaudio==0.11.0+cu113 -f https://download.pytorch.org/whl/cu113/torch_stable.html
```
Next, install spaCy with the extras for your CUDA version and transformers. The
-CUDA extra (e.g., `cuda92`, `cuda102`, `cuda111`) installs the correct version
-of [`cupy`](https://docs.cupy.dev/en/stable/install.html#installing-cupy), which
-is just like `numpy`, but for GPU. You may also need to set the `CUDA_PATH`
+CUDA extra (e.g., `cuda102`, `cuda113`) installs the correct version of
+[`cupy`](https://docs.cupy.dev/en/stable/install.html#installing-cupy), which is
+just like `numpy`, but for GPU. You may also need to set the `CUDA_PATH`
environment variable if your CUDA runtime is installed in a non-standard
-location. Putting it all together, if you had installed CUDA 10.2 in
+location. Putting it all together, if you had installed CUDA 11.3 in
`/opt/nvidia/cuda`, you would run:
-```bash
-### Installation with CUDA
+```bash {title="Installation with CUDA"}
$ export CUDA_PATH="/opt/nvidia/cuda"
-$ pip install -U %%SPACY_PKG_NAME[cuda102,transformers]%%SPACY_PKG_FLAGS
+$ pip install -U %%SPACY_PKG_NAME[cuda113,transformers]%%SPACY_PKG_FLAGS
```
For [`transformers`](https://huggingface.co/transformers/) v4.0.0+ and models
@@ -235,12 +231,11 @@ that require [`SentencePiece`](https://github.com/google/sentencepiece) (e.g.,
ALBERT, CamemBERT, XLNet, Marian, and T5), install the additional dependencies
with:
-```bash
-### Install sentencepiece
+```bash {title="Install sentencepiece"}
$ pip install transformers[sentencepiece]
```
-### Runtime usage {#transformers-runtime}
+### Runtime usage {id="transformers-runtime"}
Transformer models can be used as **drop-in replacements** for other types of
neural networks, so your spaCy pipeline can include them in a way that's
@@ -249,7 +244,7 @@ the standard way, like any other spaCy pipeline. Instead of using the
transformers as subnetworks directly, you can also use them via the
[`Transformer`](/api/transformer) pipeline component.
-
+
The `Transformer` component sets the
[`Doc._.trf_data`](/api/transformer#custom_attributes) extension attribute,
@@ -257,12 +252,11 @@ which lets you access the transformers outputs at runtime. The trained
transformer-based [pipelines](/models) provided by spaCy end on `_trf`, e.g.
[`en_core_web_trf`](/models/en#en_core_web_trf).
-```cli
+```bash
$ python -m spacy download en_core_web_trf
```
-```python
-### Example
+```python {title="Example"}
import spacy
from thinc.api import set_gpu_allocator, require_gpu
@@ -299,7 +293,7 @@ assert isinstance(doc._.custom_attr, TransformerData)
print(doc._.custom_attr.tensors)
```
-### Training usage {#transformers-training}
+### Training usage {id="transformers-training"}
The recommended workflow for training is to use spaCy's
[config system](/usage/training#config), usually via the
@@ -309,14 +303,13 @@ of objects by referring to creation functions, including functions you register
yourself. For details on how to get started with training your own model, check
out the [training quickstart](/usage/training#quickstart).
-
+{/* */}
The `[components]` section in the [`config.cfg`](/api/data-formats#config)
describes the pipeline components and the settings used to construct them,
@@ -344,8 +337,7 @@ component:
> )
> ```
-```ini
-### config.cfg (excerpt)
+```ini {title="config.cfg",excerpt="true"}
[components.transformer]
factory = "transformer"
max_batch_items = 4096
@@ -405,7 +397,7 @@ all defaults.
-### Customizing the settings {#transformers-training-custom-settings}
+### Customizing the settings {id="transformers-training-custom-settings"}
To change any of the settings, you can edit the `config.cfg` and re-run the
training. To change any of the functions, like the span getter, you can replace
@@ -425,8 +417,7 @@ subsentences of at most `max_length` tokens are returned.
> max_length = 25
> ```
-```python
-### code.py
+```python {title="code.py"}
import spacy_transformers
@spacy_transformers.registry.span_getters("custom_sent_spans")
@@ -454,11 +445,11 @@ function. You can make it available via the `--code` argument that can point to
a Python file. For more details on training with custom code, see the
[training documentation](/usage/training#custom-functions).
-```cli
+```bash
python -m spacy train ./config.cfg --code ./code.py
```
-### Customizing the model implementations {#training-custom-model}
+### Customizing the model implementations {id="training-custom-model"}
The [`Transformer`](/api/transformer) component expects a Thinc
[`Model`](https://thinc.ai/docs/api-model) object to be passed in as its `model`
@@ -476,8 +467,7 @@ is where we'll plug in our transformer model, using the
[TransformerListener](/api/architectures#TransformerListener) layer, which
sneakily delegates to the `Transformer` pipeline component.
-```ini
-### config.cfg (excerpt) {highlight="12"}
+```ini {title="config.cfg (excerpt)",highlight="12"}
[components.ner]
factory = "ner"
@@ -517,7 +507,7 @@ custom learning rate for each component. Instead of a constant, you can also
provide a schedule, allowing you to freeze the shared parameters at the start of
training.
-## Static vectors {#static-vectors}
+## Static vectors {id="static-vectors"}
If your pipeline includes a **word vectors table**, you'll be able to use the
`.similarity()` method on the [`Doc`](/api/doc), [`Span`](/api/span),
@@ -530,8 +520,8 @@ models, which can **improve the accuracy** of your components.
Word vectors in spaCy are "static" in the sense that they are not learned
parameters of the statistical models, and spaCy itself does not feature any
algorithms for learning word vector tables. You can train a word vectors table
-using tools such as [Gensim](https://radimrehurek.com/gensim/),
-[FastText](https://fasttext.cc/) or
+using tools such as [floret](https://github.com/explosion/floret),
+[Gensim](https://radimrehurek.com/gensim/), [FastText](https://fasttext.cc/) or
[GloVe](https://nlp.stanford.edu/projects/glove/), or download existing
pretrained vectors. The [`init vectors`](/api/cli#init-vectors) command lets you
convert vectors for use with spaCy and will give you a directory you can load or
@@ -546,7 +536,7 @@ the usage guide on
-### Using word vectors in your models {#word-vectors-models}
+### Using word vectors in your models {id="word-vectors-models"}
Many neural network models are able to use word vector tables as additional
features, which sometimes results in significant improvements in accuracy.
@@ -579,7 +569,7 @@ handled by the [StaticVectors](/api/architectures#StaticVectors) layer.
-#### Creating a custom embedding layer {#custom-embedding-layer}
+#### Creating a custom embedding layer {id="custom-embedding-layer"}
The [MultiHashEmbed](/api/architectures#StaticVectors) layer is spaCy's
recommended strategy for constructing initial word representations for your
@@ -642,7 +632,7 @@ def MyCustomVectors(
)
```
-## Pretraining {#pretraining}
+## Pretraining {id="pretraining"}
The [`spacy pretrain`](/api/cli#pretrain) command lets you initialize your
models with **information from raw text**. Without pretraining, the models for
@@ -678,14 +668,14 @@ You can add a `[pretraining]` block to your config by setting the
`--pretraining` flag on [`init config`](/api/cli#init-config) or
[`init fill-config`](/api/cli#init-fill-config):
-```cli
+```bash
$ python -m spacy init fill-config config.cfg config_pretrain.cfg --pretraining
```
You can then run [`spacy pretrain`](/api/cli#pretrain) with the updated config
and pass in optional config overrides, like the path to the raw text file:
-```cli
+```bash
$ python -m spacy pretrain config_pretrain.cfg ./output --paths.raw_text text.jsonl
```
@@ -699,7 +689,7 @@ change the [objective](#pretraining-objectives).
%%GITHUB_SPACY/spacy/default_config_pretraining.cfg
```
-### How pretraining works {#pretraining-details}
+### How pretraining works {id="pretraining-details"}
The impact of [`spacy pretrain`](/api/cli#pretrain) varies, but it will usually
be worth trying if you're **not using a transformer** model and you have
@@ -725,7 +715,7 @@ a "tok2vec" layer). The most common workflow is to use the
[`Tok2Vec`](/api/tok2vec) component to create a shared token-to-vector layer for
several components of your pipeline, and apply pretraining to its whole model.
-#### Configuring the pretraining {#pretraining-configure}
+#### Configuring the pretraining {id="pretraining-configure"}
The [`spacy pretrain`](/api/cli#pretrain) command is configured using the
`[pretraining]` section of your [config file](/usage/training#config). The
@@ -736,8 +726,7 @@ whole model), or a
spaCy's built-in model architectures have a reference named `"tok2vec"` that
will refer to the right layer.
-```ini
-### config.cfg
+```ini {title="config.cfg"}
# 1. Use the whole model of the "tok2vec" component
[pretraining]
component = "tok2vec"
@@ -749,7 +738,7 @@ component = "textcat"
layer = "tok2vec"
```
-#### Connecting pretraining to training {#pretraining-training}
+#### Connecting pretraining to training {id="pretraining-training"}
To benefit from pretraining, your training step needs to know to initialize its
`tok2vec` component with the weights learned from the pretraining step. You do
@@ -760,8 +749,7 @@ A pretraining step that runs for 5 epochs with an output path of `pretrain/`, as
an example, produces `pretrain/model0.bin` through `pretrain/model4.bin`. To
make use of the final output, you could fill in this value in your config file:
-```ini
-### config.cfg
+```ini {title="config.cfg"}
[paths]
init_tok2vec = "pretrain/model4.bin"
@@ -780,7 +768,7 @@ an existing pipeline, so it goes in `initialize.init_tok2vec`.
-#### Pretraining objectives {#pretraining-objectives}
+#### Pretraining objectives {id="pretraining-objectives"}
> ```ini
> ### Characters objective
diff --git a/website/docs/usage/facts-figures.md b/website/docs/usage/facts-figures.mdx
similarity index 92%
rename from website/docs/usage/facts-figures.md
rename to website/docs/usage/facts-figures.mdx
index 4bee31ed0..75ef7e4f2 100644
--- a/website/docs/usage/facts-figures.md
+++ b/website/docs/usage/facts-figures.mdx
@@ -8,7 +8,7 @@ menu:
# TODO: - ['Citing spaCy', 'citation']
---
-## Comparison {#comparison hidden="true"}
+## Comparison {id="comparison",hidden="true"}
spaCy is a **free, open-source library** for advanced **Natural Language
Processing** (NLP) in Python. It's designed specifically for **production use**
@@ -16,13 +16,11 @@ and helps you build applications that process and "understand" large volumes of
text. It can be used to build information extraction or natural language
understanding systems.
-### Feature overview {#comparison-features}
-
-import Features from 'widgets/features.js'
+### Feature overview {id="comparison-features"}
-### When should I use spaCy? {#comparison-usage}
+### When should I use spaCy? {id="comparison-usage"}
- ✅ **I'm a beginner and just getting started with NLP.** – spaCy makes it easy
to get started and comes with extensive documentation, including a
@@ -51,13 +49,13 @@ import Features from 'widgets/features.js'
can use it to make the results of your research easily available for others to
use, e.g. via a custom spaCy component.
-## Benchmarks {#benchmarks}
+## Benchmarks {id="benchmarks"}
spaCy v3.0 introduces transformer-based pipelines that bring spaCy's accuracy
right up to **current state-of-the-art**. You can also use a CPU-optimized
pipeline, which is less accurate but much cheaper to run.
-
+{/* TODO: update benchmarks and intro */}
> #### Evaluation details
>
@@ -69,8 +67,6 @@ pipeline, which is less accurate but much cheaper to run.
> gold-standard segmentation and tokenization, from a pretty specific type of
> text (articles from a single newspaper, 1984-1989).
-import Benchmarks from 'usage/\_benchmarks-models.md'
-
@@ -81,7 +77,7 @@ import Benchmarks from 'usage/\_benchmarks-models.md'
| [Mrini et al.](https://khalilmrini.github.io/Label_Attention_Layer.pdf) (2019) | 97.4 | 96.3 |
| [Zhou and Zhao](https://www.aclweb.org/anthology/P19-1230/) (2019) | 97.2 | 95.7 |
-
+
**Dependency parsing accuracy** on the Penn Treebank. See
[NLP-progress](http://nlpprogress.com/english/dependency_parsing.html) for more
@@ -92,7 +88,7 @@ results. Project template:
-### Speed comparison {#benchmarks-speed}
+### Speed comparison {id="benchmarks-speed"}
We compare the speed of different NLP libraries, measured in words per second
(WPS) - higher is better. The evaluation was performed on 10,000 Reddit
@@ -108,7 +104,7 @@ comments.
| Flair | `pos`(`-fast`) & `ner`(`-fast`) | 323 | 1,184 |
| UDPipe | `english-ewt-ud-2.5` | 1,101 | _n/a_ |
-
+
**End-to-end processing speed** on raw unannotated text. Project template:
[`benchmarks/speed`](%%GITHUB_PROJECTS/benchmarks/speed).
@@ -117,6 +113,4 @@ comments.
-
+{/* TODO: ## Citing spaCy {id="citation"} */}
diff --git a/website/docs/usage/index.md b/website/docs/usage/index.mdx
similarity index 81%
rename from website/docs/usage/index.md
rename to website/docs/usage/index.mdx
index 54ab62467..a5b7990d6 100644
--- a/website/docs/usage/index.md
+++ b/website/docs/usage/index.mdx
@@ -16,18 +16,16 @@ menu:
> website to [**v2.spacy.io**](https://v2.spacy.io/docs). To see what's changed
> and how to migrate, see the [v3.0 guide](/usage/v3).
-import QuickstartInstall from 'widgets/quickstart-install.js'
-
-## Installation instructions {#installation}
+## Installation instructions {id="installation"}
spaCy is compatible with **64-bit CPython 3.6+** and runs on **Unix/Linux**,
**macOS/OS X** and **Windows**. The latest spaCy releases are available over
[pip](https://pypi.python.org/pypi/spacy) and
[conda](https://anaconda.org/conda-forge/spacy).
-### pip {#pip}
+### pip {id="pip"}
Using pip, spaCy releases are available as source packages and binary wheels.
Before you install spaCy and its dependencies, make sure that your `pip`,
@@ -38,7 +36,7 @@ Before you install spaCy and its dependencies, make sure that your `pip`,
> After installation you typically want to download a trained pipeline. For more
> info and available packages, see the [models directory](/models).
>
-> ```cli
+> ```bash
> $ python -m spacy download en_core_web_sm
>
> >>> import spacy
@@ -75,12 +73,11 @@ spaCy's [`setup.cfg`](%%GITHUB_SPACY/setup.cfg) for details on what's included.
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `lookups` | Install [`spacy-lookups-data`](https://github.com/explosion/spacy-lookups-data) for data tables for lemmatization and lexeme normalization. The data is serialized with trained pipelines, so you only need this package if you want to train your own models. |
| `transformers` | Install [`spacy-transformers`](https://github.com/explosion/spacy-transformers). The package will be installed automatically when you install a transformer-based pipeline. |
-| `ray` | Install [`spacy-ray`](https://github.com/explosion/spacy-ray) to add CLI commands for [parallel training](/usage/training#parallel-training). |
| `cuda`, ... | Install spaCy with GPU support provided by [CuPy](https://cupy.chainer.org) for your given CUDA version. See the GPU [installation instructions](#gpu) for details and options. |
| `apple` | Install [`thinc-apple-ops`](https://github.com/explosion/thinc-apple-ops) to improve performance on an Apple M1. |
| `ja`, `ko`, `th` | Install additional dependencies required for tokenization for the [languages](/usage/models#languages). |
-### conda {#conda}
+### conda {id="conda"}
Thanks to our great community, we've been able to re-add conda support. You can
also install spaCy via `conda-forge`:
@@ -93,7 +90,7 @@ For the feedstock including the build recipe and configuration, check out
[this repository](https://github.com/conda-forge/spacy-feedstock). Note that we
currently don't publish any [pre-releases](#changelog-pre) on conda.
-### Upgrading spaCy {#upgrading}
+### Upgrading spaCy {id="upgrading"}
> #### Upgrading from v2 to v3
>
@@ -117,27 +114,26 @@ version. If incompatible packages are found, tips and installation instructions
are printed. It's recommended to run the command with `python -m` to make sure
you're executing the correct version of spaCy.
-```cli
+```bash
$ pip install -U %%SPACY_PKG_NAME%%SPACY_PKG_FLAGS
$ python -m spacy validate
```
-### Run spaCy with GPU {#gpu new="2.0.14"}
+### Run spaCy with GPU {id="gpu",version="2.0.14"}
As of v2.0, spaCy comes with neural network models that are implemented in our
machine learning library, [Thinc](https://thinc.ai). For GPU support, we've been
grateful to use the work of Chainer's [CuPy](https://cupy.chainer.org) module,
which provides a numpy-compatible interface for GPU arrays.
-spaCy can be installed on GPU by specifying `spacy[cuda]`, `spacy[cuda90]`,
-`spacy[cuda91]`, `spacy[cuda92]`, `spacy[cuda100]`, `spacy[cuda101]`,
-`spacy[cuda102]`, `spacy[cuda110]`, `spacy[cuda111]` or `spacy[cuda112]`. If you
-know your cuda version, using the more explicit specifier allows cupy to be
-installed via wheel, saving some compilation time. The specifiers should install
+spaCy can be installed for a CUDA-compatible GPU by specifying `spacy[cuda]`,
+`spacy[cuda102]`, `spacy[cuda112]`, `spacy[cuda113]`, etc. If you know your CUDA
+version, using the more explicit specifier allows CuPy to be installed via
+wheel, saving some compilation time. The specifiers should install
[`cupy`](https://cupy.chainer.org).
```bash
-$ pip install -U %%SPACY_PKG_NAME[cuda92]%%SPACY_PKG_FLAGS
+$ pip install -U %%SPACY_PKG_NAME[cuda113]%%SPACY_PKG_FLAGS
```
Once you have a GPU-enabled installation, the best way to activate it is to call
@@ -153,7 +149,7 @@ spacy.prefer_gpu()
nlp = spacy.load("en_core_web_sm")
```
-### Compile from source {#source}
+### Compile from source {id="source"}
The other way to install spaCy is to clone its
[GitHub repository](https://github.com/explosion/spaCy) and build it from
@@ -183,46 +179,87 @@ $ pip install --no-build-isolation --editable .[lookups,cuda102]
How to install compilers and related build tools:
-
-
-- **Ubuntu:** Install system-level dependencies via `apt-get`:
- `sudo apt-get install build-essential python-dev git`
-- **macOS / OS X:** Install a recent version of
- [XCode](https://developer.apple.com/xcode/), including the so-called "Command
- Line Tools". macOS and OS X ship with Python and Git preinstalled.
-- **Windows:** Install a version of the
- [Visual C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
- or
+- Ubuntu: Install system-level dependencies via
+ `apt-get`: `sudo apt-get install build-essential python-dev git`
+- macOS / OS X: Install a recent version of [XCode](https://developer.apple.com/xcode/),
+ including the so-called "Command Line Tools". macOS and OS X ship with Python and
+ Git preinstalled.
+- Windows: Install a version of the [Visual
+ C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) or
[Visual Studio Express](https://www.visualstudio.com/vs/visual-studio-express/)
that matches the version that was used to compile your Python interpreter.
-#### Additional options for developers {#source-developers}
+#### Using build constraints when compiling from source
+
+If you install spaCy from source or with `pip` for platforms where there are not
+binary wheels on PyPI, you may need to use build constraints if any package in
+your environment requires an older version of `numpy`.
+
+If `numpy` gets downgraded from the most recent release at any point after
+you've compiled `spacy`, you might see an error that looks like this:
+
+```
+numpy.ndarray size changed, may indicate binary incompatibility.
+```
+
+To fix this, create a new virtual environment and install `spacy` and all of its
+dependencies using build constraints.
+[Build constraints](https://pip.pypa.io/en/stable/user_guide/#constraints-files)
+specify an older version of `numpy` that is only used while compiling `spacy`,
+and then your runtime environment can use any newer version of `numpy` and still
+be compatible. In addition, use `--no-cache-dir` to ignore any previously cached
+wheels so that all relevant packages are recompiled from scratch:
+
+```shell
+PIP_CONSTRAINT=https://raw.githubusercontent.com/explosion/spacy/master/build-constraints.txt \
+pip install spacy --no-cache-dir
+```
+
+Our build constraints currently specify the oldest supported `numpy` available
+on PyPI for `x86_64` and `aarch64`. Depending on your platform and environment,
+you may want to customize the specific versions of `numpy`. For other platforms,
+you can have a look at SciPy's
+[`oldest-supported-numpy`](https://github.com/scipy/oldest-supported-numpy/blob/main/setup.cfg)
+package to see what the oldest recommended versions of `numpy` are.
+
+(_Warning_: don't use `pip install -c constraints.txt` instead of
+`PIP_CONSTRAINT`, since this isn't applied to the isolated build environments.)
+
+#### Additional options for developers {id="source-developers"}
Some additional options may be useful for spaCy developers who are editing the
source code and recompiling frequently.
- Install in editable mode. Changes to `.py` files will be reflected as soon as
the files are saved, but edits to Cython files (`.pxd`, `.pyx`) will require
- the `pip install` or `python setup.py build_ext` command below to be run
- again. Before installing in editable mode, be sure you have removed any
- previous installs with `pip uninstall spacy`, which you may need to run
- multiple times to remove all traces of earlier installs.
+ the `pip install` command below to be run again. Before installing in editable
+ mode, be sure you have removed any previous installs with
+ `pip uninstall spacy`, which you may need to run multiple times to remove all
+ traces of earlier installs.
```bash
$ pip install -r requirements.txt
$ pip install --no-build-isolation --editable .
```
-- Build in parallel using `N` CPUs to speed up compilation and then install in
- editable mode:
+- Build in parallel. Starting in v3.4.0, you can specify the number of build
+ jobs with the environment variable `SPACY_NUM_BUILD_JOBS`:
```bash
$ pip install -r requirements.txt
- $ python setup.py build_ext --inplace -j N
+ $ SPACY_NUM_BUILD_JOBS=4 pip install --no-build-isolation --editable .
+ ```
+
+- For editable mode and parallel builds with `python setup.py` instead of `pip`
+ (no longer recommended):
+
+ ```bash
+ $ pip install -r requirements.txt
+ $ python setup.py build_ext --inplace -j 4
$ python setup.py develop
```
-### Building an executable {#executable}
+### Building an executable {id="executable"}
The spaCy repository includes a [`Makefile`](%%GITHUB_SPACY/Makefile) that
builds an executable zip file using [`pex`](https://github.com/pantsbuild/pex)
@@ -256,7 +293,7 @@ You can configure the build process with the following environment variables:
| `PYVER` | The Python version to build against. This version needs to be available on your build and runtime machines. Defaults to `3.6`. |
| `WHEELHOUSE` | Directory to store the wheel files during compilation. Defaults to `./wheelhouse`. |
-### Run tests {#run-tests}
+### Run tests {id="run-tests"}
spaCy comes with an [extensive test suite](%%GITHUB_SPACY/spacy/tests). In order
to run the tests, you'll usually want to clone the [repository](%%GITHUB_SPACY)
@@ -282,7 +319,7 @@ $ python -m pytest --pyargs %%SPACY_PKG_NAME # basic tests
$ python -m pytest --pyargs %%SPACY_PKG_NAME --slow # basic and slow tests
```
-## Troubleshooting guide {#troubleshooting}
+## Troubleshooting guide {id="troubleshooting"}
This section collects some of the most common errors you may come across when
installing, loading and using spaCy, as well as their solutions. Also see the
@@ -408,8 +445,6 @@ either of these, clone your repository again.
-## Changelog {#changelog}
-
-import Changelog from 'widgets/changelog.js'
+## Changelog {id="changelog"}
diff --git a/website/docs/usage/layers-architectures.md b/website/docs/usage/layers-architectures.mdx
similarity index 91%
rename from website/docs/usage/layers-architectures.md
rename to website/docs/usage/layers-architectures.mdx
index 2e23b3684..37f11e8e2 100644
--- a/website/docs/usage/layers-architectures.md
+++ b/website/docs/usage/layers-architectures.mdx
@@ -40,8 +40,7 @@ this config, you won't be able to change it anymore. The architecture is like a
recipe for the network, and you can't change the recipe once the dish has
already been prepared. You have to make a new one.
-```ini
-### config.cfg (excerpt)
+```ini {title="config.cfg (excerpt)"}
[components.tagger]
factory = "tagger"
@@ -51,7 +50,7 @@ width = 512
classes = 16
```
-## Type signatures {#type-sigs}
+## Type signatures {id="type-sigs"}
> #### Example
>
@@ -111,11 +110,14 @@ If you're using a modern editor like Visual Studio Code, you can
custom Thinc plugin and get live feedback about mismatched types as you write
code.
-[](https://thinc.ai/docs/usage-type-checking#linting)
+
-## Swapping model architectures {#swap-architectures}
+## Swapping model architectures {id="swap-architectures"}
If no model is specified for the [`TextCategorizer`](/api/textcategorizer), the
[TextCatEnsemble](/api/architectures#TextCatEnsemble) architecture is used by
@@ -123,8 +125,7 @@ default. This architecture combines a simple bag-of-words model with a neural
network, usually resulting in the most accurate results, but at the cost of
speed. The config file for this model would look something like this:
-```ini
-### config.cfg (excerpt)
+```ini {title="config.cfg (excerpt)"}
[components.textcat]
factory = "textcat"
labels = []
@@ -162,8 +163,7 @@ use those by swapping out the definition of the textcat's model. For instance,
to use the simple and fast bag-of-words model
[TextCatBOW](/api/architectures#TextCatBOW), you can change the config to:
-```ini
-### config.cfg (excerpt) {highlight="6-10"}
+```ini {title="config.cfg (excerpt)",highlight="6-10"}
[components.textcat]
factory = "textcat"
labels = []
@@ -180,7 +180,7 @@ For details on all pre-defined architectures shipped with spaCy and how to
configure them, check out the [model architectures](/api/architectures)
documentation.
-### Defining sublayers {#sublayers}
+### Defining sublayers {id="sublayers"}
Model architecture functions often accept **sublayers as arguments**, so that
you can try **substituting a different layer** into the network. Depending on
@@ -195,8 +195,7 @@ These steps together compute dense, context-sensitive representations of the
tokens, and their combination forms a typical
[`Tok2Vec`](/api/architectures#Tok2Vec) layer:
-```ini
-### config.cfg (excerpt)
+```ini {title="config.cfg (excerpt)"}
[components.tok2vec]
factory = "tok2vec"
@@ -217,8 +216,7 @@ a sublayer for another one, for instance changing the first sublayer to a
character embedding with the [CharacterEmbed](/api/architectures#CharacterEmbed)
architecture:
-```ini
-### config.cfg (excerpt)
+```ini {title="config.cfg (excerpt)"}
[components.tok2vec.model.embed]
@architectures = "spacy.CharacterEmbed.v2"
# ...
@@ -237,7 +235,7 @@ a transformer. And if you want to define your own solution, all you need to do
is register a ~~Model[List[Doc], List[Floats2d]]~~ architecture function, and
you'll be able to try it out in any of the spaCy components.
-## Wrapping PyTorch, TensorFlow and other frameworks {#frameworks}
+## Wrapping PyTorch, TensorFlow and other frameworks {id="frameworks"}
Thinc allows you to [wrap models](https://thinc.ai/docs/usage-frameworks)
written in other machine learning frameworks like PyTorch, TensorFlow and MXNet
@@ -257,8 +255,7 @@ Let's use PyTorch to define a very simple neural network consisting of two
hidden `Linear` layers with `ReLU` activation and dropout, and a
softmax-activated output layer:
-```python
-### PyTorch model
+```python {title="PyTorch model"}
from torch import nn
torch_model = nn.Sequential(
@@ -300,7 +297,7 @@ layers, and "native" Thinc layers to do fiddly input and output transformations
and add on task-specific "heads", as efficiency is less of a consideration for
those parts of the network.
-### Using wrapped models {#frameworks-usage}
+### Using wrapped models {id="frameworks-usage"}
To use our custom model including the PyTorch subnetwork, all we need to do is
register the architecture using the
@@ -309,8 +306,7 @@ architecture a name so spaCy knows how to find it, and allows passing in
arguments like hyperparameters via the [config](/usage/training#config). The
full example then becomes:
-```python
-### Registering the architecture {highlight="9"}
+```python {title="Registering the architecture",highlight="9"}
from typing import List
from thinc.types import Floats2d
from thinc.api import Model, PyTorchWrapper, chain, with_array
@@ -349,8 +345,7 @@ by specifying it in the config file. In this configuration, all required
parameters for the various subcomponents of the custom architecture are passed
in as settings via the config.
-```ini
-### config.cfg (excerpt) {highlight="5-5"}
+```ini {title="config.cfg (excerpt)",highlight="5-5"}
[components.tagger]
factory = "tagger"
@@ -378,13 +373,12 @@ GPU memory allocator accordingly. When `gpu_allocator` is set to "pytorch" or
respective libraries, preventing OOM errors when there's available memory
sitting in the other library's pool.
-```ini
-### config.cfg (excerpt)
+```ini {title="config.cfg (excerpt)"}
[training]
gpu_allocator = "pytorch"
```
-## Custom models with Thinc {#thinc}
+## Custom models with Thinc {id="thinc"}
Of course it's also possible to define the `Model` from the previous section
entirely in Thinc. The Thinc documentation provides details on the
@@ -418,7 +412,7 @@ the PyTorch layers are defined, where `in_features` precedes `out_features`.
-### Shape inference in Thinc {#thinc-shape-inference}
+### Shape inference in Thinc {id="thinc-shape-inference"}
It is **not** strictly necessary to define all the input and output dimensions
for each layer, as Thinc can perform
@@ -458,8 +452,7 @@ you have to call
[`Model.initialize`](https://thinc.ai/docs/api-model#initialize) with an **input
sample** `X` and an **output sample** `Y` with the correct dimensions:
-```python
-### Shape inference with initialization {highlight="3,7,10"}
+```python {title="Shape inference with initialization",highlight="3,7,10"}
with Model.define_operators({">>": chain}):
layers = (
Relu(hidden_width)
@@ -479,7 +472,7 @@ data. In this case, `X` is typically a ~~List[Doc]~~, while `Y` is typically a
functionality is triggered when [`nlp.initialize`](/api/language#initialize) is
called.
-### Dropout and normalization in Thinc {#thinc-dropout-norm}
+### Dropout and normalization in Thinc {id="thinc-dropout-norm"}
Many of the available Thinc [layers](https://thinc.ai/docs/api-layers) allow you
to define a `dropout` argument that will result in "chaining" an additional
@@ -500,7 +493,7 @@ with Model.define_operators({">>": chain}):
model.initialize(X=input_sample, Y=output_sample)
```
-## Create new trainable components {#components}
+## Create new trainable components {id="components"}
In addition to [swapping out](#swap-architectures) layers in existing
components, you can also implement an entirely new,
@@ -518,7 +511,7 @@ overview of the `TrainablePipe` methods used by
-### Example: Entity relation extraction component {#component-rel}
+### Example: Entity relation extraction component {id="component-rel"}
This section outlines an example use-case of implementing a **novel relation
extraction component** from scratch. We'll implement a binary relation
@@ -537,18 +530,18 @@ two major steps required:
pass through the `nlp` pipeline.
-Run this example use-case by using our project template. It includes all the
-code to create the ML model and the pipeline component from scratch.
-It also contains two config files to train the model:
-one to run on CPU with a Tok2Vec layer, and one for the GPU using a transformer.
-The project applies the relation extraction component to identify biomolecular
-interactions in a sample dataset, but you can easily swap in your own dataset
-for your experiments in any other domain.
+ Run this example use-case by using our project template. It includes all the
+ code to create the ML model and the pipeline component from scratch. It also
+ contains two config files to train the model: one to run on CPU with a Tok2Vec
+ layer, and one for the GPU using a transformer. The project applies the
+ relation extraction component to identify biomolecular interactions in a
+ sample dataset, but you can easily swap in your own dataset for your
+ experiments in any other domain.
-#### Step 1: Implementing the Model {#component-rel-model}
+#### Step 1: Implementing the Model {id="component-rel-model"}
We need to implement a [`Model`](https://thinc.ai/docs/api-model) that takes a
**list of documents** (~~List[Doc]~~) as input, and outputs a **two-dimensional
@@ -561,8 +554,7 @@ matrix** (~~Floats2d~~) of predictions:
> type checks and validation. See the section on [type signatures](#type-sigs)
> for details.
-```python
-### The model architecture
+```python {title="The model architecture"}
@spacy.registry.architectures("rel_model.v1")
def create_relation_model(...) -> Model[List[Doc], Floats2d]:
model = ... # 👈 model will go here
@@ -587,8 +579,7 @@ transforms the instance tensor into a final tensor holding the predictions:
> # ...
> ```
-```python
-### The model architecture {highlight="6"}
+```python {title="The model architecture",highlight="6"}
@spacy.registry.architectures("rel_model.v1")
def create_relation_model(
create_instance_tensor: Model[List[Doc], Floats2d],
@@ -611,8 +602,7 @@ The `classification_layer` could be something like a
> nO = null
> ```
-```python
-### The classification layer
+```python {title="The classification layer"}
@spacy.registry.architectures("rel_classification_layer.v1")
def create_classification_layer(
nO: int = None, nI: int = None
@@ -648,8 +638,7 @@ that has the full implementation.
> # ...
> ```
-```python
-### The layer that creates the instance tensor
+```python {title="The layer that creates the instance tensor"}
@spacy.registry.architectures("rel_instance_tensor.v1")
def create_tensors(
tok2vec: Model[List[Doc], List[Floats2d]],
@@ -729,8 +718,7 @@ are within a **maximum distance** (in number of tokens) of each other:
> max_length = 100
> ```
-```python
-### Candidate generation
+```python {title="Candidate generation"}
@spacy.registry.misc("rel_instance_generator.v1")
def create_instances(max_length: int) -> Callable[[Doc], List[Tuple[Span, Span]]]:
def get_candidates(doc: "Doc") -> List[Tuple[Span, Span]]:
@@ -748,7 +736,7 @@ This function is added to the [`@misc` registry](/api/top-level#registry) so we
can refer to it from the config, and easily swap it out for any other candidate
generation function.
-#### Intermezzo: define how to store the relations data {#component-rel-attribute}
+#### Intermezzo: define how to store the relations data {id="component-rel-attribute"}
> #### Example output
>
@@ -773,22 +761,20 @@ above 0.5 to be a `True` relation. The ~~Example~~ instances that we'll use as
training data, will include their gold-standard relation annotations in
`example.reference._.rel`.
-```python
-### Registering the extension attribute
+```python {title="Registering the extension attribute"}
from spacy.tokens import Doc
Doc.set_extension("rel", default={})
```
-#### Step 2: Implementing the pipeline component {#component-rel-pipe}
+#### Step 2: Implementing the pipeline component {id="component-rel-pipe"}
To use our new relation extraction model as part of a custom
[trainable component](/usage/processing-pipelines#trainable-components), we
create a subclass of [`TrainablePipe`](/api/pipe) that holds the model.
-
+
-```python
-### Pipeline component skeleton
+```python {title="Pipeline component skeleton"}
from spacy.pipeline import TrainablePipe
class RelationExtractor(TrainablePipe):
@@ -825,8 +811,7 @@ and the name of this component. Additionally, this component, just like the
will predict scores for each label. We add convenience methods to easily
retrieve and add to them.
-```python
-### The constructor (continued)
+```python {title="The constructor (continued)"}
def __init__(self, vocab, model, name="rel"):
"""Create a component instance."""
# ...
@@ -855,8 +840,7 @@ will be used to do
layers of the neural network. This is triggered by calling
[`Model.initialize`](https://thinc.ai/api/model#initialize).
-```python
-### The initialize method {highlight="12,15,18,22"}
+```python {title="The initialize method",highlight="12,15,18,22"}
from itertools import islice
def initialize(
@@ -896,8 +880,7 @@ update the weights of the model layers. Thinc provides several
[loss functions](https://thinc.ai/docs/api-loss) that can be used for the
implementation of the `get_loss` function.
-```python
-### The update method {highlight="12-14"}
+```python {title="The update method",highlight="12-14"}
def update(
self,
examples: Iterable[Example],
@@ -923,8 +906,7 @@ delegate to the internal model's
[predict](https://thinc.ai/docs/api-model#predict) function that takes a batch
of `Doc` objects and returns a ~~Floats2d~~ array:
-```python
-### The predict method
+```python {title="The predict method"}
def predict(self, docs: Iterable[Doc]) -> Floats2d:
predictions = self.model.predict(docs)
return self.model.ops.asarray(predictions)
@@ -941,8 +923,7 @@ need to refer to the model's `get_instances` function that defined which pairs
of entities were relevant candidates, so that the predictions can be linked to
those exact entities:
-```python
-### The set_annotations method {highlight="5-6,10"}
+```python {title="The set_annotations method",highlight="5-6,10"}
def set_annotations(self, docs: Iterable[Doc], predictions: Floats2d):
c = 0
get_instances = self.model.attrs["get_instances"]
@@ -959,8 +940,7 @@ def set_annotations(self, docs: Iterable[Doc], predictions: Floats2d):
Under the hood, when the pipe is applied to a document, it delegates to the
`predict` and `set_annotations` methods:
-```python
-### The __call__ method
+```python {title="The __call__ method"}
def __call__(self, doc: Doc):
predictions = self.predict([doc])
self.set_annotations([doc], predictions)
@@ -971,8 +951,7 @@ There is one more optional method to implement: [`score`](/api/pipe#score)
calculates the performance of your component on a set of examples, and returns
the results as a dictionary:
-```python
-### The score method
+```python {title="The score method"}
def score(self, examples: Iterable[Example]) -> Dict[str, Any]:
prf = PRFScore()
for example in examples:
@@ -1011,8 +990,7 @@ assigns it a name and lets you create the component with
> rel_micro_f = 1.0
> ```
-```python
-### Registering the pipeline component
+```python {title="Registering the pipeline component"}
from spacy.language import Language
@Language.factory("relation_extractor")
@@ -1024,8 +1002,7 @@ You can extend the decorator to include information such as the type of
annotations that are required for this component to run, the type of annotations
it produces, and the scores that can be calculated:
-```python
-### Factory annotations {highlight="5-11"}
+```python {title="Factory annotations",highlight="5-11"}
from spacy.language import Language
@Language.factory(
@@ -1043,11 +1020,10 @@ def make_relation_extractor(nlp, name, model):
```
-Run this example use-case by using our project template. It includes all the
-code to create the ML model and the pipeline component from scratch.
-It contains two config files to train the model:
-one to run on CPU with a Tok2Vec layer, and one for the GPU using a transformer.
-The project applies the relation extraction component to identify biomolecular
-interactions, but you can easily swap in your own dataset for your experiments
-in any other domain.
+ Run this example use-case by using our project template. It includes all the
+ code to create the ML model and the pipeline component from scratch. It
+ contains two config files to train the model: one to run on CPU with a Tok2Vec
+ layer, and one for the GPU using a transformer. The project applies the
+ relation extraction component to identify biomolecular interactions, but you
+ can easily swap in your own dataset for your experiments in any other domain.
diff --git a/website/docs/usage/linguistic-features.md b/website/docs/usage/linguistic-features.mdx
similarity index 91%
rename from website/docs/usage/linguistic-features.md
rename to website/docs/usage/linguistic-features.mdx
index f8baf5588..55d5680fe 100644
--- a/website/docs/usage/linguistic-features.md
+++ b/website/docs/usage/linguistic-features.mdx
@@ -11,8 +11,8 @@ menu:
- ['Tokenization', 'tokenization']
- ['Merging & Splitting', 'retokenization']
- ['Sentence Segmentation', 'sbd']
- - ['Vectors & Similarity', 'vectors-similarity']
- ['Mappings & Exceptions', 'mappings-exceptions']
+ - ['Vectors & Similarity', 'vectors-similarity']
- ['Language Data', 'language-data']
---
@@ -26,9 +26,7 @@ information. That's exactly what spaCy is designed to do: you put in raw text,
and get back a [`Doc`](/api/doc) object, that comes with a variety of
annotations.
-## Part-of-speech tagging {#pos-tagging model="tagger, parser"}
-
-import PosDeps101 from 'usage/101/\_pos-deps.md'
+## Part-of-speech tagging {id="pos-tagging",model="tagger, parser"}
@@ -40,7 +38,7 @@ in the [models directory](/models).
-## Morphology {#morphology}
+## Morphology {id="morphology"}
Inflectional morphology is the process by which a root form of a word is
modified by adding prefixes or suffixes that specify its grammatical function
@@ -48,7 +46,7 @@ but do not change its part-of-speech. We say that a **lemma** (root form) is
**inflected** (modified/combined) with one or more **morphological features** to
create a surface form. Here are some examples:
-| Context | Surface | Lemma | POS | Morphological Features |
+| Context | Surface | Lemma | POS | Morphological Features |
| ---------------------------------------- | ------- | ----- | ------ | ---------------------------------------- |
| I was reading the paper | reading | read | `VERB` | `VerbForm=Ger` |
| I don't watch the news, I read the paper | read | read | `VERB` | `VerbForm=Fin`, `Mood=Ind`, `Tense=Pres` |
@@ -64,8 +62,7 @@ allows you to access individual morphological features.
> and express that it's a pronoun in the third person.
> 2. Inspect `token.morph` for the other tokens.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.load("en_core_web_sm")
@@ -76,14 +73,13 @@ print(token.morph) # 'Case=Nom|Number=Sing|Person=1|PronType=Prs'
print(token.morph.get("PronType")) # ['Prs']
```
-### Statistical morphology {#morphologizer new="3" model="morphologizer"}
+### Statistical morphology {id="morphologizer",version="3",model="morphologizer"}
spaCy's statistical [`Morphologizer`](/api/morphologizer) component assigns the
morphological features and coarse-grained part-of-speech tags as `Token.morph`
and `Token.pos`.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.load("de_core_news_sm")
@@ -92,7 +88,7 @@ print(doc[2].morph) # 'Case=Nom|Number=Sing|Person=2|PronType=Prs'
print(doc[2].pos_) # 'PRON'
```
-### Rule-based morphology {#rule-based-morphology}
+### Rule-based morphology {id="rule-based-morphology"}
For languages with relatively simple morphological systems like English, spaCy
can assign morphological features through a rule-based approach, which uses the
@@ -108,8 +104,7 @@ coarse-grained part-of-speech tags and morphological features.
[mapping table](#mappings-exceptions) maps the fine-grained tags to a
coarse-grained POS tags and morphological features.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.load("en_core_web_sm")
@@ -118,15 +113,17 @@ print(doc[2].morph) # 'Case=Nom|Person=2|PronType=Prs'
print(doc[2].pos_) # 'PRON'
```
-## Lemmatization {#lemmatization model="lemmatizer" new="3"}
+## Lemmatization {id="lemmatization",model="lemmatizer",version="3"}
-The [`Lemmatizer`](/api/lemmatizer) is a pipeline component that provides lookup
-and rule-based lemmatization methods in a configurable component. An individual
-language can extend the `Lemmatizer` as part of its
-[language data](#language-data).
+spaCy provides two pipeline components for lemmatization:
-```python
-### {executable="true"}
+1. The [`Lemmatizer`](/api/lemmatizer) component provides lookup and rule-based
+ lemmatization methods in a configurable component. An individual language can
+ extend the `Lemmatizer` as part of its [language data](#language-data).
+2. The [`EditTreeLemmatizer`](/api/edittreelemmatizer)
+ 3.3 component provides a trainable lemmatizer.
+
+```python {executable="true"}
import spacy
# English pipelines include a rule-based lemmatizer
@@ -157,7 +154,7 @@ provided trained pipelines already include all the required tables, but if you
are creating new pipelines, you'll probably want to install `spacy-lookups-data`
to provide the data when the lemmatizer is initialized.
-### Lookup lemmatizer {#lemmatizer-lookup}
+### Lookup lemmatizer {id="lemmatizer-lookup"}
For pipelines without a tagger or morphologizer, a lookup lemmatizer can be
added to the pipeline as long as a lookup table is provided, typically through
@@ -173,7 +170,7 @@ nlp = spacy.blank("sv")
nlp.add_pipe("lemmatizer", config={"mode": "lookup"})
```
-### Rule-based lemmatizer {#lemmatizer-rule}
+### Rule-based lemmatizer {id="lemmatizer-rule"}
When training pipelines that include a component that assigns part-of-speech
tags (a morphologizer or a tagger with a [POS mapping](#mappings-exceptions)), a
@@ -197,7 +194,21 @@ information, without consulting the context of the token. The rule-based
lemmatizer also accepts list-based exception files. For English, these are
acquired from [WordNet](https://wordnet.princeton.edu/).
-## Dependency Parsing {#dependency-parse model="parser"}
+### Trainable lemmatizer
+
+The [`EditTreeLemmatizer`](/api/edittreelemmatizer) can learn form-to-lemma
+transformations from a training corpus that includes lemma annotations. This
+removes the need to write language-specific rules and can (in many cases)
+provide higher accuracies than lookup and rule-based lemmatizers.
+
+```python
+import spacy
+
+nlp = spacy.blank("de")
+nlp.add_pipe("trainable_lemmatizer", name="lemmatizer")
+```
+
+## Dependency Parsing {id="dependency-parse",model="parser"}
spaCy features a fast and accurate syntactic dependency parser, and has a rich
API for navigating the tree. The parser also powers the sentence boundary
@@ -215,7 +226,7 @@ different languages, see the label schemes documented in the
-### Noun chunks {#noun-chunks}
+### Noun chunks {id="noun-chunks"}
Noun chunks are "base noun phrases" – flat phrases that have a noun as their
head. You can think of noun chunks as a noun plus the words describing the noun
@@ -223,8 +234,7 @@ head. You can think of noun chunks as a noun plus the words describing the noun
get the noun chunks in a document, simply iterate over
[`Doc.noun_chunks`](/api/doc#noun_chunks).
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.load("en_core_web_sm")
@@ -246,7 +256,7 @@ for chunk in doc.noun_chunks:
| insurance liability | liability | `dobj` | shift |
| manufacturers | manufacturers | `pobj` | toward |
-### Navigating the parse tree {#navigating}
+### Navigating the parse tree {id="navigating"}
spaCy uses the terms **head** and **child** to describe the words **connected by
a single arc** in the dependency tree. The term **dep** is used for the arc
@@ -254,8 +264,7 @@ label, which describes the type of syntactic relation that connects the child to
the head. As with other attributes, the value of `.dep` is a hash value. You can
get the string value with `.dep_`.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.load("en_core_web_sm")
@@ -281,17 +290,18 @@ for token in doc:
| toward | `prep` | shift | `NOUN` | manufacturers |
| manufacturers | `pobj` | toward | `ADP` | |
-import DisplaCyLong2Html from 'images/displacy-long2.html'
-
-
+
Because the syntactic relations form a tree, every word has **exactly one
head**. You can therefore iterate over the arcs in the tree by iterating over
the words in the sentence. This is usually the best way to match an arc of
interest – from below:
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy.symbols import nsubj, VERB
@@ -323,7 +333,7 @@ for possible_verb in doc:
To iterate through the children, use the `token.children` attribute, which
provides a sequence of [`Token`](/api/token) objects.
-#### Iterating around the local tree {#navigating-around}
+#### Iterating around the local tree {id="navigating-around"}
A few more convenience attributes are provided for iterating around the local
tree from the token. [`Token.lefts`](/api/token#lefts) and
@@ -334,8 +344,7 @@ order. There are also two integer-typed attributes,
[`Token.n_rights`](/api/token#n_rights) that give the number of left and right
children.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.load("en_core_web_sm")
@@ -346,8 +355,7 @@ print(doc[2].n_lefts) # 2
print(doc[2].n_rights) # 1
```
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.load("de_core_news_sm")
@@ -370,8 +378,7 @@ sequence of tokens. You can walk up the tree with the
> true for the German pipelines, which have many
> [non-projective dependencies](https://explosion.ai/blog/german-model#word-order).
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.load("en_core_web_sm")
@@ -400,8 +407,7 @@ easiest way to create a `Span` object for a syntactic phrase. Note that
`.right_edge` gives a token **within** the subtree – so if you use it as the
end-point of a range, don't forget to `+1`!
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.load("en_core_web_sm")
@@ -413,7 +419,7 @@ for token in doc:
print(token.text, token.pos_, token.dep_, token.head.text)
```
-| Text | POS | Dep | Head text |
+| Text | POS | Dep | Head text |
| ----------------------------------- | ------ | ------- | --------- |
| Credit and mortgage account holders | `NOUN` | `nsubj` | submit |
| must | `VERB` | `aux` | submit |
@@ -428,8 +434,7 @@ currency values, i.e. entities labeled as `MONEY`, and then uses the dependency
parse to find the noun phrase they are referring to – for example `"Net income"`
→ `"$9.4 million"`.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.load("en_core_web_sm")
@@ -463,7 +468,7 @@ see the usage guide on
-### Visualizing dependencies {#displacy}
+### Visualizing dependencies {id="displacy"}
The best way to understand spaCy's dependency parser is interactively. To make
this easier, spaCy comes with a visualization module. You can pass a `Doc` or a
@@ -474,8 +479,7 @@ If you want to know how to write rules that hook into some type of syntactic
construction, just plug the sentence into the visualizer and see how spaCy
annotates it.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy import displacy
@@ -493,7 +497,7 @@ displaCy in our [online demo](https://explosion.ai/demos/displacy)..
-### Disabling the parser {#disabling}
+### Disabling the parser {id="disabling"}
In the [trained pipelines](/models) provided by spaCy, the parser is loaded and
enabled by default as part of the
@@ -508,7 +512,7 @@ the `nlp` object. For more details, see the usage guide on
nlp = spacy.load("en_core_web_sm", disable=["parser"])
```
-## Named Entity Recognition {#named-entities}
+## Named Entity Recognition {id="named-entities"}
spaCy features an extremely fast statistical entity recognition system, that
assigns labels to contiguous spans of tokens. The default
@@ -517,13 +521,11 @@ entities, including companies, locations, organizations and products. You can
add arbitrary classes to the entity recognition system, and update the model
with new examples.
-### Named Entity Recognition 101 {#named-entities-101}
-
-import NER101 from 'usage/101/\_named-entities.md'
+### Named Entity Recognition 101 {id="named-entities-101"}
-### Accessing entity annotations and labels {#accessing-ner}
+### Accessing entity annotations and labels {id="accessing-ner"}
The standard way to access entity annotations is the [`doc.ents`](/api/doc#ents)
property, which produces a sequence of [`Span`](/api/span) objects. The entity
@@ -552,8 +554,7 @@ on a token, it will return an empty string.
> - `U` – Token is a single-token **unit** entity.
> - `O` – Token is **outside** an entity.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.load("en_core_web_sm")
@@ -580,7 +581,7 @@ print(ent_francisco) # ['Francisco', 'I', 'GPE']
| delivery | `2` | `O` | `""` | outside an entity |
| robots | `2` | `O` | `""` | outside an entity |
-### Setting entity annotations {#setting-entities}
+### Setting entity annotations {id="setting-entities"}
To ensure that the sequence of token annotations remains consistent, you have to
set entity annotations **at the document level**. However, you can't write
@@ -588,8 +589,7 @@ directly to the `token.ent_iob` or `token.ent_type` attributes, so the easiest
way to set entities is to use the [`doc.set_ents`](/api/doc#set_ents) function
and create the new entity as a [`Span`](/api/span).
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy.tokens import Span
@@ -622,15 +622,14 @@ indices, not the character offsets. To create a span from character offsets, use
fb_ent = doc.char_span(0, 2, label="ORG")
```
-#### Setting entity annotations from array {#setting-from-array}
+#### Setting entity annotations from array {id="setting-from-array"}
You can also assign entity annotations using the
[`doc.from_array`](/api/doc#from_array) method. To do this, you should include
both the `ENT_TYPE` and the `ENT_IOB` attributes in the array you're importing
from.
-```python
-### {executable="true"}
+```python {executable="true"}
import numpy
import spacy
from spacy.attrs import ENT_IOB, ENT_TYPE
@@ -647,7 +646,7 @@ doc.from_array(header, attr_array)
print("After", doc.ents) # [London]
```
-#### Setting entity annotations in Cython {#setting-cython}
+#### Setting entity annotations in Cython {id="setting-cython"}
Finally, you can always write to the underlying struct if you compile a
[Cython](http://cython.org/) function. This is easy to do, and allows you to
@@ -669,7 +668,7 @@ cpdef set_entity(Doc doc, int start, int end, attr_t ent_type):
Obviously, if you write directly to the array of `TokenC*` structs, you'll have
responsibility for ensuring that the data is left in a consistent state.
-### Built-in entity types {#entity-types}
+### Built-in entity types {id="entity-types"}
> #### Tip: Understanding entity types
>
@@ -685,7 +684,7 @@ For details on the entity types available in spaCy's trained pipelines, see the
-### Visualizing named entities {#displacy}
+### Visualizing named entities {id="displacy"}
The
[displaCy ENT visualizer](https://explosion.ai/demos/displacy-ent)
@@ -699,8 +698,7 @@ list of `Doc` objects to displaCy and run
For more details and examples, see the
[usage guide on visualizing spaCy](/usage/visualizers).
-```python
-### Named Entity example
+```python {title="Named Entity example"}
import spacy
from spacy import displacy
@@ -711,11 +709,13 @@ doc = nlp(text)
displacy.serve(doc, style="ent")
```
-import DisplacyEntHtml from 'images/displacy-ent2.html'
+
-
-
-## Entity Linking {#entity-linking}
+## Entity Linking {id="entity-linking"}
To ground the named entities into the "real world", spaCy provides functionality
to perform entity linking, which resolves a textual entity to a unique
@@ -723,7 +723,7 @@ identifier from a knowledge base (KB). You can create your own
[`KnowledgeBase`](/api/kb) and [train](/usage/training) a new
[`EntityLinker`](/api/entitylinker) using that custom knowledge base.
-### Accessing entity identifiers {#entity-linking-accessing model="entity linking"}
+### Accessing entity identifiers {id="entity-linking-accessing",model="entity linking"}
The annotated KB identifier is accessible as either a hash value or as a string,
using the attributes `ent.kb_id` and `ent.kb_id_` of a [`Span`](/api/span)
@@ -749,7 +749,7 @@ print(ent_ada_1) # ['Lovelace', 'PERSON', 'Q7259']
print(ent_london_5) # ['London', 'GPE', 'Q84']
```
-## Tokenization {#tokenization}
+## Tokenization {id="tokenization"}
Tokenization is the task of splitting a text into meaningful segments, called
_tokens_. The input to the tokenizer is a unicode text, and the output is a
@@ -768,8 +768,6 @@ during tokenization. This is kind of a core principle of spaCy's `Doc` object:
-import Tokenization101 from 'usage/101/\_tokenization.md'
-
@@ -799,6 +797,10 @@ def tokenizer_pseudo_code(
for substring in text.split():
suffixes = []
while substring:
+ if substring in special_cases:
+ tokens.extend(special_cases[substring])
+ substring = ""
+ continue
while prefix_search(substring) or suffix_search(substring):
if token_match(substring):
tokens.append(substring)
@@ -851,20 +853,22 @@ def tokenizer_pseudo_code(
The algorithm can be summarized as follows:
1. Iterate over space-separated substrings.
-2. Look for a token match. If there is a match, stop processing and keep this
- token.
-3. Check whether we have an explicitly defined special case for this substring.
+2. Check whether we have an explicitly defined special case for this substring.
If we do, use it.
-4. Otherwise, try to consume one prefix. If we consumed a prefix, go back to #2,
+3. Look for a token match. If there is a match, stop processing and keep this
+ token.
+4. Check whether we have an explicitly defined special case for this substring.
+ If we do, use it.
+5. Otherwise, try to consume one prefix. If we consumed a prefix, go back to #3,
so that the token match and special cases always get priority.
-5. If we didn't consume a prefix, try to consume a suffix and then go back to
- #2.
-6. If we can't consume a prefix or a suffix, look for a URL match.
-7. If there's no URL match, then look for a special case.
-8. Look for "infixes" – stuff like hyphens etc. and split the substring into
+6. If we didn't consume a prefix, try to consume a suffix and then go back to
+ #3.
+7. If we can't consume a prefix or a suffix, look for a URL match.
+8. If there's no URL match, then look for a special case.
+9. Look for "infixes" – stuff like hyphens etc. and split the substring into
tokens on all infixes.
-9. Once we can't consume any more of the string, handle it as a single token.
-10. Make a final pass over the text to check for special cases that include
+10. Once we can't consume any more of the string, handle it as a single token.
+11. Make a final pass over the text to check for special cases that include
spaces or that were missed due to the incremental processing of affixes.
@@ -891,15 +895,14 @@ might make sense to create an entirely custom subclass.
---
-### Adding special case tokenization rules {#special-cases}
+### Adding special case tokenization rules {id="special-cases"}
Most domains have at least some idiosyncrasies that require custom tokenization
rules. This could be very certain expressions, or abbreviations only used in
this specific field. Here's how to add a special case rule to an existing
[`Tokenizer`](/api/tokenizer) instance:
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy.symbols import ORTH
@@ -928,7 +931,7 @@ nlp.tokenizer.add_special_case("...gimme...?", [{"ORTH": "...gimme...?"}])
assert len(nlp("...gimme...?")) == 1
```
-#### Debugging the tokenizer {#tokenizer-debug new="2.2.3"}
+#### Debugging the tokenizer {id="tokenizer-debug",version="2.2.3"}
A working implementation of the pseudo-code above is available for debugging as
[`nlp.tokenizer.explain(text)`](/api/tokenizer#explain). It returns a list of
@@ -946,8 +949,7 @@ tokens produced are identical to `nlp.tokenizer()` except for whitespace tokens:
> " SUFFIX
> ```
-```python
-### {executable="true"}
+```python {executable="true"}
from spacy.lang.en import English
nlp = English()
@@ -959,7 +961,7 @@ for t in tok_exp:
print(t[1], "\\t", t[0])
```
-### Customizing spaCy's Tokenizer class {#native-tokenizers}
+### Customizing spaCy's Tokenizer class {id="native-tokenizers"}
Let's imagine you wanted to create a tokenizer for a new language or specific
domain. There are six things you may need to define:
@@ -981,8 +983,7 @@ You shouldn't usually need to create a `Tokenizer` subclass. Standard usage is
to use `re.compile()` to build a regular expression object, and pass its
`.search()` and `.finditer()` methods:
-```python
-### {executable="true"}
+```python {executable="true"}
import re
import spacy
from spacy.tokenizer import Tokenizer
@@ -1022,7 +1023,7 @@ only be applied at the **end of a token**, so your expression should end with a
-#### Modifying existing rule sets {#native-tokenizer-additions}
+#### Modifying existing rule sets {id="native-tokenizer-additions"}
In many situations, you don't necessarily need entirely custom rules. Sometimes
you just want to add another character to the prefixes, suffixes or infixes. The
@@ -1075,8 +1076,7 @@ letters as an infix. If you do not want the tokenizer to split on hyphens
between letters, you can modify the existing infix definition from
[`lang/punctuation.py`](%%GITHUB_SPACY/spacy/lang/punctuation.py):
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy.lang.char_classes import ALPHA, ALPHA_LOWER, ALPHA_UPPER
from spacy.lang.char_classes import CONCAT_QUOTES, LIST_ELLIPSES, LIST_ICONS
@@ -1115,7 +1115,7 @@ language-specific definitions such as
[`lang/de/punctuation.py`](%%GITHUB_SPACY/spacy/lang/de/punctuation.py) for
German.
-### Hooking a custom tokenizer into the pipeline {#custom-tokenizer}
+### Hooking a custom tokenizer into the pipeline {id="custom-tokenizer"}
The tokenizer is the first component of the processing pipeline and the only one
that can't be replaced by writing to `nlp.pipeline`. This is because it has a
@@ -1123,7 +1123,7 @@ different signature from all the other components: it takes a text and returns a
[`Doc`](/api/doc), whereas all other components expect to already receive a
tokenized `Doc`.
-
+
To overwrite the existing tokenizer, you need to replace `nlp.tokenizer` with a
custom function that takes a text and returns a [`Doc`](/api/doc).
@@ -1152,7 +1152,7 @@ nlp.tokenizer = my_tokenizer
| `text` | `str` | The raw text to tokenize. |
| **RETURNS** | [`Doc`](/api/doc) | The tokenized document. |
-#### Example 1: Basic whitespace tokenizer {#custom-tokenizer-example}
+#### Example 1: Basic whitespace tokenizer {id="custom-tokenizer-example"}
Here's an example of the most basic whitespace tokenizer. It takes the shared
vocab, so it can construct `Doc` objects. When it's called on a text, it returns
@@ -1160,8 +1160,7 @@ a `Doc` object consisting of the text split on single space characters. We can
then overwrite the `nlp.tokenizer` attribute with an instance of our custom
tokenizer.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy.tokens import Doc
@@ -1183,7 +1182,7 @@ class WhitespaceTokenizer:
spaces = spaces[0:-1]
else:
spaces[-1] = False
-
+
return Doc(self.vocab, words=words, spaces=spaces)
nlp = spacy.blank("en")
@@ -1192,7 +1191,7 @@ doc = nlp("What's happened to me? he thought. It wasn't a dream.")
print([token.text for token in doc])
```
-#### Example 2: Third-party tokenizers (BERT word pieces) {#custom-tokenizer-example2}
+#### Example 2: Third-party tokenizers (BERT word pieces) {id="custom-tokenizer-example2"}
You can use the same approach to plug in any other third-party tokenizers. Your
custom callable just needs to return a `Doc` object with the tokens produced by
@@ -1211,8 +1210,7 @@ produced by the tokenizer.
> **training transformer models** in spaCy, as well as helpful utilities for
> aligning word pieces to linguistic tokenization.
-```python
-### Custom BERT word piece tokenizer
+```python {title="Custom BERT word piece tokenizer"}
from tokenizers import BertWordPieceTokenizer
from spacy.tokens import Doc
import spacy
@@ -1256,15 +1254,15 @@ tokenizer** it will be using at runtime. See the docs on
-#### Training with custom tokenization {#custom-tokenizer-training new="3"}
+#### Training with custom tokenization {id="custom-tokenizer-training",version="3"}
spaCy's [training config](/usage/training#config) describes the settings,
hyperparameters, pipeline and tokenizer used for constructing and training the
pipeline. The `[nlp.tokenizer]` block refers to a **registered function** that
takes the `nlp` object and returns a tokenizer. Here, we're registering a
function called `whitespace_tokenizer` in the
-[`@tokenizers` registry](/api/top-level#registry). To make sure spaCy knows how to
-construct your tokenizer during training, you can pass in your Python file by
+[`@tokenizers` registry](/api/top-level#registry). To make sure spaCy knows how
+to construct your tokenizer during training, you can pass in your Python file by
setting `--code functions.py` when you run [`spacy train`](/api/cli#train).
> #### config.cfg
@@ -1274,8 +1272,7 @@ setting `--code functions.py` when you run [`spacy train`](/api/cli#train).
> @tokenizers = "whitespace_tokenizer"
> ```
-```python
-### functions.py {highlight="1"}
+```python {title="functions.py",highlight="1"}
@spacy.registry.tokenizers("whitespace_tokenizer")
def create_whitespace_tokenizer():
def create_tokenizer(nlp):
@@ -1300,8 +1297,7 @@ correct type.
> lowercase = true
> ```
-```python
-### functions.py {highlight="1"}
+```python {title="functions.py",highlight="1"}
@spacy.registry.tokenizers("bert_word_piece_tokenizer")
def create_whitespace_tokenizer(vocab_file: str, lowercase: bool):
def create_tokenizer(nlp):
@@ -1325,7 +1321,7 @@ takes a text and returns a `Doc`.
-#### Using pre-tokenized text {#own-annotations}
+#### Using pre-tokenized text {id="own-annotations"}
spaCy generally assumes by default that your data is **raw text**. However,
sometimes your data is partially annotated, e.g. with pre-existing tokenization,
@@ -1344,8 +1340,7 @@ boolean values, indicating whether each word is followed by a space.
> `Doc` with `words` and `spaces` so that the `doc.text` matches the original
> input text.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy.tokens import Doc
@@ -1365,7 +1360,7 @@ will assume that all words are followed by a space. Once you have a
part-of-speech tags, syntactic dependencies, named entities and other
attributes.
-#### Aligning tokenization {#aligning-tokenization}
+#### Aligning tokenization {id="aligning-tokenization"}
spaCy's tokenization is non-destructive and uses language-specific rules
optimized for compatibility with treebank annotations. Other tools and resources
@@ -1391,17 +1386,16 @@ token.
> 3. Make `other_tokens` and `spacy_tokens` identical. You'll see that all
> tokens now correspond 1-to-1.
-```python
-### {executable="true"}
+```python {executable="true"}
from spacy.training import Alignment
other_tokens = ["i", "listened", "to", "obama", "'", "s", "podcasts", "."]
spacy_tokens = ["i", "listened", "to", "obama", "'s", "podcasts", "."]
align = Alignment.from_strings(other_tokens, spacy_tokens)
print(f"a -> b, lengths: {align.x2y.lengths}") # array([1, 1, 1, 1, 1, 1, 1, 1])
-print(f"a -> b, mapping: {align.x2y.dataXd}") # array([0, 1, 2, 3, 4, 4, 5, 6]) : two tokens both refer to "'s"
+print(f"a -> b, mapping: {align.x2y.data}") # array([0, 1, 2, 3, 4, 4, 5, 6]) : two tokens both refer to "'s"
print(f"b -> a, lengths: {align.y2x.lengths}") # array([1, 1, 1, 1, 2, 1, 1]) : the token "'s" refers to two tokens
-print(f"b -> a, mappings: {align.y2x.dataXd}") # array([0, 1, 2, 3, 4, 5, 6, 7])
+print(f"b -> a, mappings: {align.y2x.data}") # array([0, 1, 2, 3, 4, 5, 6, 7])
```
Here are some insights from the alignment information generated in the example
@@ -1410,10 +1404,10 @@ above:
- The one-to-one mappings for the first four tokens are identical, which means
they map to each other. This makes sense because they're also identical in the
input: `"i"`, `"listened"`, `"to"` and `"obama"`.
-- The value of `x2y.dataXd[6]` is `5`, which means that `other_tokens[6]`
+- The value of `x2y.data[6]` is `5`, which means that `other_tokens[6]`
(`"podcasts"`) aligns to `spacy_tokens[5]` (also `"podcasts"`).
-- `x2y.dataXd[4]` and `x2y.dataXd[5]` are both `4`, which means that both tokens
- 4 and 5 of `other_tokens` (`"'"` and `"s"`) align to token 4 of `spacy_tokens`
+- `x2y.data[4]` and `x2y.data[5]` are both `4`, which means that both tokens 4
+ and 5 of `other_tokens` (`"'"` and `"s"`) align to token 4 of `spacy_tokens`
(`"'s"`).
@@ -1425,7 +1419,7 @@ tokenizations add up to the same string. For example, you'll be able to align
-## Merging and splitting {#retokenization new="2.1"}
+## Merging and splitting {id="retokenization",version="2.1"}
The [`Doc.retokenize`](/api/doc#retokenize) context manager lets you merge and
split tokens. Modifications to the tokenization are stored and performed all at
@@ -1444,8 +1438,7 @@ root.
> recognized as a named entity, this change will also be reflected in the
> `doc.ents`.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.load("en_core_web_sm")
@@ -1514,8 +1507,7 @@ second split subtoken) and "York" should be attached to "in".
> 3. Split the token into three tokens instead of two – for example,
> `["New", "Yo", "rk"]`.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy import displacy
@@ -1544,8 +1536,7 @@ the token indices after splitting.
If you don't care about the heads (for example, if you're only running the
tokenizer and not the parser), you can attach each subtoken to itself:
-```python
-### {highlight="3"}
+```python {highlight="3"}
doc = nlp("I live in NewYorkCity")
with doc.retokenize() as retokenizer:
heads = [(doc[3], 0), (doc[3], 1), (doc[3], 2)]
@@ -1569,7 +1560,7 @@ with doc.retokenize() as retokenizer:
-### Overwriting custom extension attributes {#retokenization-extensions}
+### Overwriting custom extension attributes {id="retokenization-extensions"}
If you've registered custom
[extension attributes](/usage/processing-pipelines#custom-components-attributes),
@@ -1601,8 +1592,7 @@ values can't be overwritten. For more details, see the
> you need to provide a list of extension attribute values as the `"_"`
> property, one for each split subtoken.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy.tokens import Token
@@ -1618,7 +1608,7 @@ with doc.retokenize() as retokenizer:
print("After:", [(token.text, token._.is_musician) for token in doc])
```
-## Sentence Segmentation {#sbd}
+## Sentence Segmentation {id="sbd"}
A [`Doc`](/api/doc) object's sentences are available via the `Doc.sents`
property. To view a `Doc`'s sentences, you can iterate over the `Doc.sents`, a
@@ -1627,8 +1617,7 @@ has sentence boundaries by calling
[`Doc.has_annotation`](/api/doc#has_annotation) with the attribute name
`"SENT_START"`.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.load("en_core_web_sm")
@@ -1653,7 +1642,7 @@ spaCy provides four alternatives for sentence segmentation:
processing pipeline can set sentence boundaries by writing to
`Token.is_sent_start`.
-### Default: Using the dependency parse {#sbd-parser model="parser"}
+### Default: Using the dependency parse {id="sbd-parser",model="parser"}
Unlike other libraries, spaCy uses the dependency parse to determine sentence
boundaries. This is usually the most accurate approach, but it requires a
@@ -1663,8 +1652,7 @@ with spaCy's provided trained pipelines. For social media or conversational text
that doesn't follow the same rules, your application may benefit from a custom
trained or rule-based component.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.load("en_core_web_sm")
@@ -1678,7 +1666,7 @@ your `Doc` using custom components _before_ it's parsed. Depending on your text,
this may also improve parse accuracy, since the parser is constrained to predict
parses consistent with the sentence boundaries.
-### Statistical sentence segmenter {#sbd-senter model="senter" new="3"}
+### Statistical sentence segmenter {id="sbd-senter",model="senter",version="3"}
The [`SentenceRecognizer`](/api/sentencerecognizer) is a simple statistical
component that only provides sentence boundaries. Along with being faster and
@@ -1698,8 +1686,7 @@ without the parser and then enable the sentence recognizer explicitly with
> which is better at predicting sentence boundaries when punctuation is not
> present.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.load("en_core_web_sm", exclude=["parser"])
@@ -1709,15 +1696,14 @@ for sent in doc.sents:
print(sent.text)
```
-### Rule-based pipeline component {#sbd-component}
+### Rule-based pipeline component {id="sbd-component"}
The [`Sentencizer`](/api/sentencizer) component is a
[pipeline component](/usage/processing-pipelines) that splits sentences on
punctuation like `.`, `!` or `?`. You can plug it into your pipeline if you only
need sentence boundaries without dependency parses.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy.lang.en import English
@@ -1756,8 +1742,7 @@ for unset sentence boundaries. This approach can be useful if you want to
implement **additional** rules specific to your data, while still being able to
take advantage of dependency-based sentence segmentation.
-```python
-### {executable="true"}
+```python {executable="true"}
from spacy.language import Language
import spacy
@@ -1779,7 +1764,7 @@ doc = nlp(text)
print("After:", [sent.text for sent in doc.sents])
```
-## Mappings & Exceptions {#mappings-exceptions new="3"}
+## Mappings & Exceptions {id="mappings-exceptions",version="3"}
The [`AttributeRuler`](/api/attributeruler) manages **rule-based mappings and
exceptions** for all token-level attributes. As the number of
@@ -1807,8 +1792,7 @@ The following example shows how the tag and POS `NNP`/`PROPN` can be specified
for the phrase `"The Who"`, overriding the tags provided by the statistical
tagger and the POS tag map.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.load("en_core_web_sm")
@@ -1843,13 +1827,11 @@ initialized before training. See the
-## Word vectors and semantic similarity {#vectors-similarity}
-
-import Vectors101 from 'usage/101/\_vectors-similarity.md'
+## Word vectors and semantic similarity {id="vectors-similarity"}
-### Adding word vectors {#adding-vectors}
+### Adding word vectors {id="adding-vectors"}
Custom word vectors can be trained using a number of open-source libraries, such
as [Gensim](https://radimrehurek.com/gensim), [FastText](https://fasttext.cc),
@@ -1875,8 +1857,8 @@ access to some nice Latin vectors. You can then pass the directory path to
> doc1.similarity(doc2)
> ```
-```cli
-$ wget https://s3-us-west-1.amazonaws.com/fasttext-vectors/word-vectors-v2/cc.la.300.vec.gz
+```bash
+$ wget https://dl.fbaipublicfiles.com/fasttext/vectors-crawl/cc.la.300.vec.gz
$ python -m spacy init vectors en cc.la.300.vec.gz /tmp/la_vectors_wiki_lg
```
@@ -1913,8 +1895,7 @@ the removed words, mapped to `(string, score)` tuples, where `string` is the
entry the removed word was mapped to and `score` the similarity score between
the two words.
-```python
-### Removed words
+```python {title="Removed words"}
{
"Shore": ("coast", 0.732257),
"Precautionary": ("caution", 0.490973),
@@ -1935,7 +1916,7 @@ the vector of "leaving", which is identical. If you're using the
option to easily reduce the size of the vectors as you add them to a spaCy
pipeline:
-```cli
+```bash
$ python -m spacy init vectors en la.300d.vec.tgz /tmp/la_vectors_web_md --prune 10000
```
@@ -1945,7 +1926,7 @@ among those retained.
-### Adding vectors individually {#adding-individual-vectors}
+### Adding vectors individually {id="adding-individual-vectors"}
The `vector` attribute is a **read-only** numpy or cupy array (depending on
whether you've configured spaCy to use GPU memory), with dtype `float32`. The
@@ -1959,8 +1940,7 @@ be slower than approaches that work with the whole vectors table at once, but
it's a great approach for once-off conversions before you save out your `nlp`
object to disk.
-```python
-### Adding vectors
+```python {title="Adding vectors"}
from spacy.vocab import Vocab
vector_data = {
@@ -1973,13 +1953,11 @@ for word, vector in vector_data.items():
vocab.set_vector(word, vector)
```
-## Language Data {#language-data}
-
-import LanguageData101 from 'usage/101/\_language-data.md'
+## Language Data {id="language-data"}
-### Creating a custom language subclass {#language-subclass}
+### Creating a custom language subclass {id="language-subclass"}
If you want to customize multiple components of the language data or add support
for a custom language or domain-specific "dialect", you can also implement your
@@ -1988,8 +1966,7 @@ own language subclass. The subclass should define two attributes: the `lang`
overview of the available attributes that can be overwritten, see the
[`Language.Defaults`](/api/language#defaults) documentation.
-```python
-### {executable="true"}
+```python {executable="true"}
from spacy.lang.en import English
class CustomEnglishDefaults(English.Defaults):
@@ -2027,12 +2004,11 @@ language name, and even train pipelines with it and refer to it in your
> needs to be available during training. You can load a Python file containing
> the code using the `--code` argument:
>
-> ```cli
+> ```bash
> python -m spacy train config.cfg --code code.py
> ```
-```python
-### Registering a custom language {highlight="7,12-13"}
+```python {title="Registering a custom language",highlight="7,12-13"}
import spacy
from spacy.lang.en import English
diff --git a/website/docs/usage/models.md b/website/docs/usage/models.mdx
similarity index 81%
rename from website/docs/usage/models.md
rename to website/docs/usage/models.mdx
index 3b79c4d0d..3b8a5fa3f 100644
--- a/website/docs/usage/models.md
+++ b/website/docs/usage/models.mdx
@@ -23,33 +23,14 @@ located anywhere on your file system.
## Quickstart {hidden="true"}
-import QuickstartModels from 'widgets/quickstart-models.js'
+
-
+### Usage note
-## Language support {#languages}
-
-spaCy currently provides support for the following languages. You can help by
-improving the existing [language data](/usage/linguistic-features#language-data)
-and extending the tokenization patterns.
-[See here](https://github.com/explosion/spaCy/issues/3056) for details on how to
-contribute to development. Also see the
-[training documentation](/usage/training) for how to train your own pipelines on
-your data.
-
-> #### Usage note
->
-> If a trained pipeline is available for a language, you can download it using
-> the [`spacy download`](/api/cli#download) command. In order to use languages
-> that don't yet come with a trained pipeline, you have to import them directly,
-> or use [`spacy.blank`](/api/top-level#spacy.blank):
->
-> ```python
-> from spacy.lang.fi import Finnish
-> nlp = Finnish() # use directly
-> nlp = spacy.blank("fi") # blank instance
-> ```
->
> If lemmatization rules are available for your language, make sure to install
> spaCy with the `lookups` option, or install
> [`spacy-lookups-data`](https://github.com/explosion/spacy-lookups-data)
@@ -59,11 +40,37 @@ your data.
> $ pip install -U %%SPACY_PKG_NAME[lookups]%%SPACY_PKG_FLAGS
> ```
-import Languages from 'widgets/languages.js'
+If a trained pipeline is available for a language, you can download it using the
+[`spacy download`](/api/cli#download) command as shown above. In order to use
+languages that don't yet come with a trained pipeline, you have to import them
+directly, or use [`spacy.blank`](/api/top-level#spacy.blank):
+
+```python
+from spacy.lang.yo import Yoruba
+nlp = Yoruba() # use directly
+nlp = spacy.blank("yo") # blank instance
+```
+
+A blank pipeline is typically just a tokenizer. You might want to create a blank
+pipeline when you only need a tokenizer, when you want to add more components
+from scratch, or for testing purposes. Initializing the language object directly
+yields the same result as generating it using `spacy.blank()`. In both cases the
+default configuration for the chosen language is loaded, and no pretrained
+components will be available.
+
+## Language support {id="languages"}
+
+spaCy currently provides support for the following languages. You can help by
+improving the existing [language data](/usage/linguistic-features#language-data)
+and extending the tokenization patterns.
+[See here](https://github.com/explosion/spaCy/issues/3056) for details on how to
+contribute to development. Also see the
+[training documentation](/usage/training) for how to train your own pipelines on
+your data.
-### Multi-language support {#multi-language new="2"}
+### Multi-language support {id="multi-language",version="2"}
> ```python
> # Standard import
@@ -82,10 +89,10 @@ generic subclass containing only the base language data, can be found in
To train a pipeline using the neutral multi-language class, you can set
`lang = "xx"` in your [training config](/usage/training#config). You can also
-import the `MultiLanguage` class directly, or call
+\import the `MultiLanguage` class directly, or call
[`spacy.blank("xx")`](/api/top-level#spacy.blank) for lazy-loading.
-### Chinese language support {#chinese new="2.3"}
+### Chinese language support {id="chinese",version="2.3"}
The Chinese language class supports three word segmentation options, `char`,
`jieba` and `pkuseg`.
@@ -106,8 +113,7 @@ The Chinese language class supports three word segmentation options, `char`,
> nlp.tokenizer.initialize(pkuseg_model="mixed")
> ```
-```ini
-### config.cfg
+```ini {title="config.cfg"}
[nlp.tokenizer]
@tokenizers = "spacy.zh.ChineseTokenizer"
segmenter = "char"
@@ -148,8 +154,7 @@ local path at runtime. See the usage guide on the
[config lifecycle](/usage/training#config-lifecycle) for more background on
this.
-```ini
-### config.cfg
+```ini {title="config.cfg"}
[initialize]
[initialize.tokenizer]
@@ -160,8 +165,7 @@ pkuseg_user_dict = "default"
You can also initialize the tokenizer for a blank language class by calling its
`initialize` method:
-```python
-### Examples
+```python {title="Examples"}
# Initialize the pkuseg tokenizer
cfg = {"segmenter": "pkuseg"}
nlp = Chinese.from_config({"nlp": {"tokenizer": cfg}})
@@ -220,7 +224,7 @@ nlp.tokenizer.initialize(pkuseg_model="/path/to/pkuseg_model")
-### Japanese language support {#japanese new=2.3}
+### Japanese language support {id="japanese",version="2.3"}
> #### Manual setup
>
@@ -240,8 +244,7 @@ segmentation and part-of-speech tagging. The default Japanese language class and
the provided Japanese pipelines use SudachiPy split mode `A`. The tokenizer
config can be used to configure the split mode to `A`, `B` or `C`.
-```ini
-### config.cfg
+```ini {title="config.cfg"}
[nlp.tokenizer]
@tokenizers = "spacy.ja.JapaneseTokenizer"
split_mode = "A"
@@ -259,7 +262,45 @@ used for training the current [Japanese pipelines](/models/ja).
-## Installing and using trained pipelines {#download}
+### Korean language support {id="korean"}
+
+> #### mecab-ko tokenizer
+>
+> ```python
+> nlp = spacy.blank("ko")
+> ```
+
+The default MeCab-based Korean tokenizer requires:
+
+- [mecab-ko](https://bitbucket.org/eunjeon/mecab-ko/src/master/README.md)
+- [mecab-ko-dic](https://bitbucket.org/eunjeon/mecab-ko-dic)
+- [natto-py](https://github.com/buruzaemon/natto-py)
+
+For some Korean datasets and tasks, the
+[rule-based tokenizer](/usage/linguistic-features#tokenization) is better-suited
+than MeCab. To configure a Korean pipeline with the rule-based tokenizer:
+
+> #### Rule-based tokenizer
+>
+> ```python
+> config = {"nlp": {"tokenizer": {"@tokenizers": "spacy.Tokenizer.v1"}}}
+> nlp = spacy.blank("ko", config=config)
+> ```
+
+```ini {title="config.cfg"}
+[nlp]
+lang = "ko"
+tokenizer = {"@tokenizers" = "spacy.Tokenizer.v1"}
+```
+
+
+
+The [Korean trained pipelines](/models/ko) use the rule-based tokenizer, so no
+additional dependencies are required.
+
+
+
+## Installing and using trained pipelines {id="download"}
The easiest way to download a trained pipeline is via spaCy's
[`download`](/api/cli#download) command. It takes care of finding the
@@ -281,7 +322,7 @@ best-matching package compatible with your spaCy installation.
> + nlp = spacy.load("en_core_web_sm")
> ```
-```cli
+```bash
# Download best-matching version of a package for your spaCy installation
$ python -m spacy download en_core_web_sm
@@ -292,7 +333,7 @@ $ python -m spacy download en_core_web_sm-3.0.0 --direct
The download command will [install the package](/usage/models#download-pip) via
pip and place the package in your `site-packages` directory.
-```cli
+```bash
$ pip install -U %%SPACY_PKG_NAME%%SPACY_PKG_FLAGS
$ python -m spacy download en_core_web_sm
```
@@ -310,24 +351,41 @@ Make sure to **restart your kernel** or runtime after installation (just like
you would when installing other Python packages) to make sure that the installed
pipeline package can be found.
-```cli
+```bash
!python -m spacy download en_core_web_sm
```
-### Installation via pip {#download-pip}
+### Installation via pip {id="download-pip"}
To download a trained pipeline directly using
[pip](https://pypi.python.org/pypi/pip), point `pip install` to the URL or local
path of the wheel file or archive. Installing the wheel is usually more
-efficient. To find the direct link to a package, head over to the
-[releases](https://github.com/explosion/spacy-models/releases), right click on
-the archive link and copy it to your clipboard.
+efficient.
+
+> #### Pipeline Package URLs {id="pipeline-urls"}
+>
+> Pretrained pipeline distributions are hosted on
+> [Github Releases](https://github.com/explosion/spacy-models/releases), and you
+> can find download links there, as well as on the model page. You can also get
+> URLs directly from the command line by using `spacy info` with the `--url`
+> flag, which may be useful for automation.
+>
+> ```bash
+> spacy info en_core_web_sm --url
+> ```
+>
+> This command will print the URL for the latest version of a pipeline
+> compatible with the version of spaCy you're using. Note that in order to look
+> up the compatibility information an internet connection is required.
```bash
# With external URL
$ pip install https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.0.0/en_core_web_sm-3.0.0-py3-none-any.whl
$ pip install https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.0.0/en_core_web_sm-3.0.0.tar.gz
+# Using spacy info to get the external URL
+$ pip install $(spacy info en_core_web_sm --url)
+
# With local file
$ pip install /Users/you/en_core_web_sm-3.0.0-py3-none-any.whl
$ pip install /Users/you/en_core_web_sm-3.0.0.tar.gz
@@ -344,7 +402,7 @@ You can also add the direct download link to your application's
`requirements.txt`. For more details, see the section on
[working with pipeline packages in production](#production).
-### Manual download and installation {#download-manual}
+### Manual download and installation {id="download-manual"}
In some cases, you might prefer downloading the data manually, for example to
place it into a custom directory. You can download the package via your browser
@@ -353,8 +411,7 @@ or configure your own download script using the URL of the archive file. The
archive consists of a package directory that contains another directory with the
pipeline data.
-```yaml
-### Directory structure {highlight="6"}
+```yaml {title="Directory structure",highlight="6"}
└── en_core_web_md-3.0.0.tar.gz # downloaded archive
├── setup.py # setup file for pip installation
├── meta.json # copy of pipeline meta
@@ -369,7 +426,7 @@ pipeline data.
You can place the **pipeline package directory** anywhere on your local file
system.
-### Installation from Python {#download-python}
+### Installation from Python {id="download-python"}
Since the [`spacy download`](/api/cli#download) command installs the pipeline as
a **Python package**, we always recommend running it from the command line, just
@@ -390,7 +447,7 @@ import spacy
spacy.cli.download("en_core_web_sm")
```
-### Using trained pipelines with spaCy {#usage}
+### Using trained pipelines with spaCy {id="usage"}
To load a pipeline package, use [`spacy.load`](/api/top-level#spacy.load) with
the package name or a path to the data directory:
@@ -417,21 +474,20 @@ doc = nlp("This is a sentence.")
You can use the [`info`](/api/cli#info) command or
-[`spacy.info()`](/api/top-level#spacy.info) method to print a pipeline
-package's meta data before loading it. Each `Language` object with a loaded
-pipeline also exposes the pipeline's meta data as the attribute `meta`. For
-example, `nlp.meta['version']` will return the package version.
+[`spacy.info()`](/api/top-level#spacy.info) method to print a pipeline package's
+meta data before loading it. Each `Language` object with a loaded pipeline also
+exposes the pipeline's meta data as the attribute `meta`. For example,
+`nlp.meta['version']` will return the package version.
-### Importing pipeline packages as modules {#usage-import}
+### Importing pipeline packages as modules {id="usage-import"}
If you've installed a trained pipeline via [`spacy download`](/api/cli#download)
or directly via pip, you can also `import` it and then call its `load()` method
with no arguments:
-```python
-### {executable="true"}
+```python {executable="true"}
import en_core_web_sm
nlp = en_core_web_sm.load()
@@ -447,7 +503,7 @@ as your code will raise an `ImportError` immediately, instead of failing
somewhere down the line when calling `spacy.load()`. For more details, see the
section on [working with pipeline packages in production](#production).
-## Using trained pipelines in production {#production}
+## Using trained pipelines in production {id="production"}
If your application depends on one or more trained pipeline packages, you'll
usually want to integrate them into your continuous integration workflow and
@@ -456,7 +512,7 @@ and loading pipeline packages, the underlying functionality is entirely based on
native Python packaging. This allows your application to handle a spaCy pipeline
like any other package dependency.
-### Downloading and requiring package dependencies {#models-download}
+### Downloading and requiring package dependencies {id="models-download"}
spaCy's built-in [`download`](/api/cli#download) command is mostly intended as a
convenient, interactive wrapper. It performs compatibility checks and prints
@@ -468,28 +524,22 @@ should be specifying them directly.
Because pipeline packages are valid Python packages, you can add them to your
application's `requirements.txt`. If you're running your own internal PyPi
installation, you can upload the pipeline packages there. pip's
-[requirements file format](https://pip.pypa.io/en/latest/reference/pip_install/#requirements-file-format)
-supports both package names to download via a PyPi server, as well as direct
-URLs.
+[requirements file format](https://pip.pypa.io/en/latest/reference/requirements-file-format/)
+supports both package names to download via a PyPi server, as well as
+[direct URLs](#pipeline-urls).
-```text
-### requirements.txt
+```text {title="requirements.txt"}
spacy>=3.0.0,<4.0.0
-https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.0.0/en_core_web_sm-3.0.0.tar.gz#egg=en_core_web_sm
+en_core_web_sm @ https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.4.0/en_core_web_sm-3.4.0-py3-none-any.whl
```
-Specifying `#egg=` with the package name tells pip which package to expect from
-the download URL. This way, the package won't be re-downloaded and overwritten
-if it's already installed - just like when you're downloading a package from
-PyPi.
-
All pipeline packages are versioned and specify their spaCy dependency. This
ensures cross-compatibility and lets you specify exact version requirements for
each pipeline. If you've [trained](/usage/training) your own pipeline, you can
use the [`spacy package`](/api/cli#package) command to generate the required
meta data and turn it into a loadable package.
-### Loading and testing pipeline packages {#models-loading}
+### Loading and testing pipeline packages {id="models-loading"}
Pipeline packages are regular Python packages, so you can also import them as a
package using Python's native `import` syntax, and then call the `load` method
diff --git a/website/docs/usage/processing-pipelines.md b/website/docs/usage/processing-pipelines.mdx
similarity index 92%
rename from website/docs/usage/processing-pipelines.md
rename to website/docs/usage/processing-pipelines.mdx
index 11fd1459d..307cb9dcb 100644
--- a/website/docs/usage/processing-pipelines.md
+++ b/website/docs/usage/processing-pipelines.mdx
@@ -12,11 +12,9 @@ menu:
- ['Plugins & Wrappers', 'plugins']
---
-import Pipelines101 from 'usage/101/\_pipelines.md'
-
-## Processing text {#processing}
+## Processing text {id="processing"}
When you call `nlp` on a text, spaCy will **tokenize** it and then **call each
component** on the `Doc`, in order. It then returns the processed `Doc` that you
@@ -62,8 +60,7 @@ so we can iterate over them and access the named entity predictions:
> 1. Also disable the `"ner"` component. You'll see that the `doc.ents` are now
> empty, because the entity recognizer didn't run.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
texts = [
@@ -97,8 +94,7 @@ the input should be a sequence of `(text, context)` tuples and the output will
be a sequence of `(doc, context)` tuples. For example, you can pass metadata in
the context and save it in a [custom attribute](#custom-components-attributes):
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy.tokens import Doc
@@ -122,7 +118,7 @@ for doc in docs:
print(f"{doc._.text_id}: {doc.text}")
```
-### Multiprocessing {#multiprocessing}
+### Multiprocessing {id="multiprocessing"}
spaCy includes built-in support for multiprocessing with
[`nlp.pipe`](/api/language#pipe) using the `n_process` option:
@@ -170,7 +166,7 @@ the number of threads before loading any models using
-## Pipelines and built-in components {#pipelines}
+## Pipelines and built-in components {id="pipelines"}
spaCy makes it very easy to create your own pipelines consisting of reusable
components – this includes spaCy's default tagger, parser and entity recognizer,
@@ -248,8 +244,7 @@ tagging pipeline. This is also why the pipeline state is always held by the
together and returns an instance of `Language` with a pipeline set and access to
the binary data:
-```python
-### spacy.load under the hood
+```python {title="spacy.load under the hood"}
lang = "en"
pipeline = ["tok2vec", "tagger", "parser", "ner", "attribute_ruler", "lemmatizer"]
data_path = "path/to/en_core_web_sm/en_core_web_sm-3.0.0"
@@ -268,8 +263,7 @@ subsequently to the `Token` and `Span` which are only views of the `Doc`, and
don't own any data themselves. All components return the modified document,
which is then processed by the next component in the pipeline.
-```python
-### The pipeline under the hood
+```python {title="The pipeline under the hood"}
doc = nlp.make_doc("This is a sentence") # Create a Doc from raw text
for name, proc in nlp.pipeline: # Iterate over components in order
doc = proc(doc) # Apply each component
@@ -286,7 +280,7 @@ print(nlp.pipe_names)
# ['tok2vec', 'tagger', 'parser', 'ner', 'attribute_ruler', 'lemmatizer']
```
-### Built-in pipeline components {#built-in}
+### Built-in pipeline components {id="built-in"}
spaCy ships with several built-in pipeline components that are registered with
string names. This means that you can initialize them by calling
@@ -303,24 +297,25 @@ available pipeline components and component functions.
> ruler = nlp.add_pipe("entity_ruler")
> ```
-| String name | Component | Description |
-| -------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| `tagger` | [`Tagger`](/api/tagger) | Assign part-of-speech-tags. |
-| `parser` | [`DependencyParser`](/api/dependencyparser) | Assign dependency labels. |
-| `ner` | [`EntityRecognizer`](/api/entityrecognizer) | Assign named entities. |
-| `entity_linker` | [`EntityLinker`](/api/entitylinker) | Assign knowledge base IDs to named entities. Should be added after the entity recognizer. |
-| `entity_ruler` | [`EntityRuler`](/api/entityruler) | Assign named entities based on pattern rules and dictionaries. |
-| `textcat` | [`TextCategorizer`](/api/textcategorizer) | Assign text categories: exactly one category is predicted per document. |
-| `textcat_multilabel` | [`MultiLabel_TextCategorizer`](/api/textcategorizer) | Assign text categories in a multi-label setting: zero, one or more labels per document. |
-| `lemmatizer` | [`Lemmatizer`](/api/lemmatizer) | Assign base forms to words. |
-| `morphologizer` | [`Morphologizer`](/api/morphologizer) | Assign morphological features and coarse-grained POS tags. |
-| `attribute_ruler` | [`AttributeRuler`](/api/attributeruler) | Assign token attribute mappings and rule-based exceptions. |
-| `senter` | [`SentenceRecognizer`](/api/sentencerecognizer) | Assign sentence boundaries. |
-| `sentencizer` | [`Sentencizer`](/api/sentencizer) | Add rule-based sentence segmentation without the dependency parse. |
-| `tok2vec` | [`Tok2Vec`](/api/tok2vec) | Assign token-to-vector embeddings. |
-| `transformer` | [`Transformer`](/api/transformer) | Assign the tokens and outputs of a transformer model. |
+| String name | Component | Description |
+| ---------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `tagger` | [`Tagger`](/api/tagger) | Assign part-of-speech-tags. |
+| `parser` | [`DependencyParser`](/api/dependencyparser) | Assign dependency labels. |
+| `ner` | [`EntityRecognizer`](/api/entityrecognizer) | Assign named entities. |
+| `entity_linker` | [`EntityLinker`](/api/entitylinker) | Assign knowledge base IDs to named entities. Should be added after the entity recognizer. |
+| `entity_ruler` | [`EntityRuler`](/api/entityruler) | Assign named entities based on pattern rules and dictionaries. |
+| `textcat` | [`TextCategorizer`](/api/textcategorizer) | Assign text categories: exactly one category is predicted per document. |
+| `textcat_multilabel` | [`MultiLabel_TextCategorizer`](/api/textcategorizer) | Assign text categories in a multi-label setting: zero, one or more labels per document. |
+| `lemmatizer` | [`Lemmatizer`](/api/lemmatizer) | Assign base forms to words using rules and lookups. |
+| `trainable_lemmatizer` | [`EditTreeLemmatizer`](/api/edittreelemmatizer) | Assign base forms to words. |
+| `morphologizer` | [`Morphologizer`](/api/morphologizer) | Assign morphological features and coarse-grained POS tags. |
+| `attribute_ruler` | [`AttributeRuler`](/api/attributeruler) | Assign token attribute mappings and rule-based exceptions. |
+| `senter` | [`SentenceRecognizer`](/api/sentencerecognizer) | Assign sentence boundaries. |
+| `sentencizer` | [`Sentencizer`](/api/sentencizer) | Add rule-based sentence segmentation without the dependency parse. |
+| `tok2vec` | [`Tok2Vec`](/api/tok2vec) | Assign token-to-vector embeddings. |
+| `transformer` | [`Transformer`](/api/transformer) | Assign the tokens and outputs of a transformer model. |
-### Disabling, excluding and modifying components {#disabling}
+### Disabling, excluding and modifying components {id="disabling"}
If you don't need a particular component of the pipeline – for example, the
tagger or the parser, you can **disable or exclude** it. This can sometimes make
@@ -361,6 +356,20 @@ nlp = spacy.load("en_core_web_sm", disable=["tagger", "parser"])
nlp.enable_pipe("tagger")
```
+In addition to `disable`, `spacy.load()` also accepts `enable`. If `enable` is
+set, all components except for those in `enable` are disabled. If `enable` and
+`disable` conflict (i.e. the same component is included in both), an error is
+raised.
+
+```python
+# Load the complete pipeline, but disable all components except for tok2vec and tagger
+nlp = spacy.load("en_core_web_sm", enable=["tok2vec", "tagger"])
+# Has the same effect, as NER is already not part of enabled set of components
+nlp = spacy.load("en_core_web_sm", enable=["tok2vec", "tagger"], disable=["ner"])
+# Will raise an error, as the sets of enabled and disabled components are conflicting
+nlp = spacy.load("en_core_web_sm", enable=["ner"], disable=["ner"])
+```
+
As of v3.0, the `disable` keyword argument specifies components to load but
@@ -377,8 +386,7 @@ call its `restore()` method to restore the disabled components when needed. This
can be useful if you want to prevent unnecessary code indentation of large
blocks.
-```python
-### Disable for block
+```python {title="Disable for block"}
# 1. Use as a context manager
with nlp.select_pipes(disable=["tagger", "parser", "lemmatizer"]):
doc = nlp("I won't be tagged and parsed")
@@ -446,7 +454,7 @@ run as part of the pipeline.
| `nlp.component_names` | All component names, including disabled components. |
| `nlp.disabled` | Names of components that are currently disabled. |
-### Sourcing components from existing pipelines {#sourced-components new="3"}
+### Sourcing components from existing pipelines {id="sourced-components",version="3"}
Pipeline components that are independent can also be reused across pipelines.
Instead of adding a new blank component, you can also copy an existing component
@@ -489,8 +497,7 @@ vectors available – otherwise, it won't be able to make the same predictions.
> frozen_components = ["ner"]
> ```
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
# The source pipeline with different components
@@ -503,7 +510,7 @@ nlp.add_pipe("ner", source=source_nlp)
print(nlp.pipe_names)
```
-### Analyzing pipeline components {#analysis new="3"}
+### Analyzing pipeline components {id="analysis",version="3"}
The [`nlp.analyze_pipes`](/api/language#analyze_pipes) method analyzes the
components in the current pipeline and outputs information about them like the
@@ -520,8 +527,7 @@ table instead of only returning the structured data.
> `"entity_linker"`. The analysis should now show no problems, because
> requirements are met.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.blank("en")
@@ -533,8 +539,7 @@ analysis = nlp.analyze_pipes(pretty=True)
-```json
-### Structured
+```json {title="Structured"}
{
"summary": {
"tagger": {
@@ -552,7 +557,12 @@ analysis = nlp.analyze_pipes(pretty=True)
},
"problems": {
"tagger": [],
- "entity_linker": ["doc.ents", "doc.sents", "token.ent_iob", "token.ent_type"]
+ "entity_linker": [
+ "doc.ents",
+ "doc.sents",
+ "token.ent_iob",
+ "token.ent_type"
+ ]
},
"attrs": {
"token.ent_iob": { "assigns": [], "requires": ["entity_linker"] },
@@ -595,7 +605,7 @@ doesn't, the pipeline analysis won't catch that.
-## Creating custom pipeline components {#custom-components}
+## Creating custom pipeline components {id="custom-components"}
A pipeline component is a function that receives a `Doc` object, modifies it and
returns it – for example, by using the current weights to make a prediction and
@@ -664,7 +674,7 @@ your custom components, and make sure they can be saved and loaded.
-### Examples: Simple stateless pipeline components {#custom-components-simple}
+### Examples: Simple stateless pipeline components {id="custom-components-simple"}
The following component receives the `Doc` in the pipeline and prints some
information about it: the number of tokens, the part-of-speech tags of the
@@ -685,8 +695,7 @@ component under the name `"info_component"`.
> else. spaCy should now complain that it doesn't know a component of the
> name `"info_component"`.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy.language import Language
@@ -719,8 +728,7 @@ boundaries.
> to `None` (missing value), the parser will assign sentence boundaries in
> between.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy.language import Language
@@ -743,7 +751,7 @@ for sent in doc.sents:
print(sent.text)
```
-### Component factories and stateful components {#custom-components-factories}
+### Component factories and stateful components {id="custom-components-factories"}
Component factories are callables that take settings and return a **pipeline
component function**. This is useful if your component is stateful and if you
@@ -773,8 +781,7 @@ All other settings can be passed in by the user via the `config` argument on
[`@Language.factory`](/api/language#factory) decorator also lets you define a
`default_config` that's used as a fallback.
-```python
-### With config {highlight="4,9"}
+```python {title="With config",highlight="4,9"}
import spacy
from spacy.language import Language
@@ -823,7 +830,7 @@ make your factory a separate function. That's also how spaCy does it internally.
-### Language-specific factories {#factories-language new="3"}
+### Language-specific factories {id="factories-language",version="3"}
There are many use cases where you might want your pipeline components to be
language-specific. Sometimes this requires entirely different implementation per
@@ -838,8 +845,7 @@ a token, the `Token.norm_` with an entry from a language-specific lookup table.
It's registered twice under the name `"token_normalizer"` – once using
`@English.factory` and once using `@German.factory`:
-```python
-### {executable="true"}
+```python {executable="true"}
from spacy.lang.en import English
from spacy.lang.de import German
@@ -881,7 +887,7 @@ available, falls back to looking up the regular factory name.
-### Example: Stateful component with settings {#example-stateful-components}
+### Example: Stateful component with settings {id="example-stateful-components"}
This example shows a **stateful** pipeline component for handling acronyms:
based on a dictionary, it will detect acronyms and their expanded forms in both
@@ -908,8 +914,7 @@ case-sensitive.
> should see an entry for the acronyms component, referencing the factory
> `acronyms` and the config settings.
-```python
-### {executable="true"}
+```python {executable="true"}
from spacy.language import Language
from spacy.tokens import Doc
from spacy.matcher import PhraseMatcher
@@ -950,7 +955,7 @@ doc = nlp("LOL, be right back")
print(doc._.acronyms)
```
-## Initializing and serializing component data {#component-data}
+## Initializing and serializing component data {id="component-data"}
Many stateful components depend on **data resources** like dictionaries and
lookup tables that should ideally be **configurable**. For example, it makes
@@ -981,7 +986,7 @@ that if a component saves out its config and settings, the
since that's the config the component was created with. It will also fail if the
data is not JSON-serializable.
-### Option 1: Using a registered function {#component-data-function}
+### Option 1: Using a registered function {id="component-data-function"}
@@ -1011,8 +1016,7 @@ argument, the name:
> batchers. `misc` is intended for miscellaneous functions that don't fit
> anywhere else.
-```python
-### Registered function for assets {highlight="1"}
+```python {title="Registered function for assets",highlight="1"}
@spacy.registry.misc("acronyms.slang_dict.v1")
def create_acronyms_slang_dict():
dictionary = {"lol": "laughing out loud", "brb": "be right back"}
@@ -1050,7 +1054,7 @@ the name. Registered functions can also take **arguments**, by the way, that can
be defined in the config as well – you can read more about this in the docs on
[training with custom code](/usage/training#custom-code).
-### Option 2: Save data with the pipeline and load it in once on initialization {#component-data-initialization}
+### Option 2: Save data with the pipeline and load it in once on initialization {id="component-data-initialization"}
@@ -1080,14 +1084,17 @@ on [serialization methods](/usage/saving-loading/#serialization-methods).
> receive the directory path `/path/acronyms` and can then create files in this
> directory.
-```python
-### Custom serialization methods {highlight="6-7,9-11"}
+```python {title="Custom serialization methods",highlight="7-11,13-15"}
import srsly
+from spacy.util import ensure_path
class AcronymComponent:
# other methods here...
def to_disk(self, path, exclude=tuple()):
+ path = ensure_path(path)
+ if not path.exists():
+ path.mkdir()
srsly.write_json(path / "data.json", self.data)
def from_disk(self, path, exclude=tuple()):
@@ -1139,7 +1146,7 @@ pipeline is loaded. For more background on this, see the usage guides on the
[config lifecycle](/usage/training#config-lifecycle) and
[custom initialization](/usage/training#initialization).
-
+
A component's `initialize` method needs to take at least **two named
arguments**: a `get_examples` callback that gives it access to the training
@@ -1159,8 +1166,7 @@ be defined via the config – in this case a dictionary `data`.
> path = "/path/to/slang_dict.json"
> ```
-```python
-### Custom initialize method {highlight="5-6"}
+```python {title="Custom initialize method",highlight="5-6"}
class AcronymComponent:
def __init__(self):
self.data = {}
@@ -1178,7 +1184,7 @@ object is saved to disk, which will run the component's `to_disk` method. When
the pipeline is loaded back into spaCy later to use it, the `from_disk` method
will load the data back in.
-## Python type hints and validation {#type-hints new="3"}
+## Python type hints and validation {id="type-hints",version="3"}
spaCy's configs are powered by our machine learning library Thinc's
[configuration system](https://thinc.ai/docs/usage-config), which supports
@@ -1223,8 +1229,7 @@ string value.
> and write a type hint for `log_level` that only accepts the exact string
> values `"DEBUG"`, `"INFO"` or `"CRITICAL"`.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy.language import Language
from spacy.tokens import Doc
@@ -1248,14 +1253,14 @@ nlp.add_pipe("debug", config={"log_level": "DEBUG"})
doc = nlp("This is a text...")
```
-## Trainable components {#trainable-components new="3"}
+## Trainable components {id="trainable-components",version="3"}
spaCy's [`TrainablePipe`](/api/pipe) class helps you implement your own
trainable components that have their own model instance, make predictions over
`Doc` objects and can be updated using [`spacy train`](/api/cli#train). This
lets you plug fully custom machine learning components into your pipeline.
-
+
You'll need the following:
@@ -1313,8 +1318,7 @@ components. It also makes the components more **modular** and lets you
[swap](/usage/layers-architectures#swap-architectures) different architectures
in your config, and re-use model definitions.
-```ini
-### config.cfg (excerpt)
+```ini {title="config.cfg (excerpt)"}
[components]
[components.textcat]
@@ -1365,7 +1369,7 @@ into your spaCy pipeline, see the usage guide on
-## Extension attributes {#custom-components-attributes new="2"}
+## Extension attributes {id="custom-components-attributes",version="2"}
spaCy allows you to set any custom attributes and methods on the `Doc`, `Span`
and `Token`, which become available as `Doc._`, `Span._` and `Token._` – for
@@ -1448,8 +1452,7 @@ particular instance. If an attribute of the same name already exists, or if
you're trying to access an attribute that hasn't been registered, spaCy will
raise an `AttributeError`.
-```python
-### Example
+```python {title="Example"}
from spacy.tokens import Doc, Span, Token
fruits = ["apple", "pear", "banana", "orange", "strawberry"]
@@ -1476,7 +1479,7 @@ Once you've registered your custom attribute, you can also use the built-in
especially useful it you want to pass in a string instead of calling
`doc._.my_attr`.
-### Example: Pipeline component for GPE entities and country meta data via a REST API {#component-example3}
+### Example: Pipeline component for GPE entities and country meta data via a REST API {id="component-example3"}
This example shows the implementation of a pipeline component that fetches
country meta data via the [REST Countries API](https://restcountries.com), sets
@@ -1484,8 +1487,7 @@ entity annotations for countries and sets custom attributes on the `Doc` and
`Span` – for example, the capital, latitude/longitude coordinates and even the
country flag.
-```python
-### {executable="true"}
+```python {executable="true"}
import requests
from spacy.lang.en import English
from spacy.language import Language
@@ -1552,7 +1554,7 @@ mistakes or foreign-language versions, you could also implement a
`like_country`-style getter function that makes a request to the search API
endpoint and returns the best-matching result.
-### User hooks {#custom-components-user-hooks}
+### User hooks {id="custom-components-user-hooks"}
While it's generally recommended to use the `Doc._`, `Span._` and `Token._`
proxies to add your own custom attributes, spaCy offers a few exceptions to
@@ -1583,8 +1585,7 @@ to `Doc.user_span_hooks` and `Doc.user_token_hooks`.
| `user_token_hooks` | [`Token.similarity`](/api/token#similarity), [`Token.vector`](/api/token#vector), [`Token.has_vector`](/api/token#has_vector), [`Token.vector_norm`](/api/token#vector_norm), [`Token.conjuncts`](/api/token#conjuncts) |
| `user_span_hooks` | [`Span.similarity`](/api/span#similarity), [`Span.vector`](/api/span#vector), [`Span.has_vector`](/api/span#has_vector), [`Span.vector_norm`](/api/span#vector_norm), [`Span.root`](/api/span#root) |
-```python
-### Add custom similarity hooks
+```python {title="Add custom similarity hooks"}
from spacy.language import Language
@@ -1608,7 +1609,7 @@ def create_similarity_component(nlp, name, index: int):
return SimilarityModel(name, index)
```
-## Developing plugins and wrappers {#plugins}
+## Developing plugins and wrappers {id="plugins"}
We're very excited about all the new possibilities for community extensions and
plugins in spaCy, and we can't wait to see what you build with it! To get you
@@ -1616,7 +1617,7 @@ started, here are a few tips, tricks and best
practices. [See here](/universe/?category=pipeline) for examples of other spaCy
extensions.
-### Usage ideas {#custom-components-usage-ideas}
+### Usage ideas {id="custom-components-usage-ideas"}
- **Adding new features and hooking in models.** For example, a sentiment
analysis model, or your preferred solution for lemmatization or sentiment
@@ -1632,7 +1633,7 @@ extensions.
exports relevant information about the current state of the processed
document, and insert it at any point of your pipeline.
-### Best practices {#custom-components-best-practices}
+### Best practices {id="custom-components-best-practices"}
Extensions can claim their own `._` namespace and exist as standalone packages.
If you're developing a tool or library and want to make it easy for others to
@@ -1720,7 +1721,7 @@ function that takes a `Doc`, modifies it and returns it.
to help people find it. If you post it on Twitter, feel free to tag
[@spacy_io](https://twitter.com/spacy_io) so we can check it out.
-### Wrapping other models and libraries {#wrapping-models-libraries}
+### Wrapping other models and libraries {id="wrapping-models-libraries"}
Let's say you have a custom entity recognizer that takes a list of strings and
returns their [BILUO tags](/usage/linguistic-features#accessing-ner). Given an
@@ -1742,8 +1743,7 @@ wrapper has to do is compute the entity spans and overwrite the `doc.ents`.
> attributes. By definition, each token can only be part of one entity, so
> overlapping entity spans are not allowed.
-```python
-### {highlight="1,8-9"}
+```python {highlight="1,8-9"}
import your_custom_entity_recognizer
from spacy.training import biluo_tags_to_spans
from spacy.language import Language
@@ -1781,8 +1781,7 @@ label scheme than spaCy's default models.
> it fully replaces the `nlp` object instead of providing a pipeline component,
> since it also needs to handle tokenization.
-```python
-### {highlight="1,11,17-19"}
+```python {highlight="1,11,17-19"}
import your_custom_model
from spacy.language import Language
from spacy.symbols import POS, TAG, DEP, HEAD
diff --git a/website/docs/usage/projects.md b/website/docs/usage/projects.mdx
similarity index 79%
rename from website/docs/usage/projects.md
rename to website/docs/usage/projects.mdx
index 57d226913..8ec035942 100644
--- a/website/docs/usage/projects.md
+++ b/website/docs/usage/projects.mdx
@@ -1,6 +1,6 @@
---
title: Projects
-new: 3
+version: 3
menu:
- ['Intro & Workflow', 'intro']
- ['Directory & Assets', 'directory']
@@ -9,7 +9,7 @@ menu:
- ['Integrations', 'integrations']
---
-## Introduction and workflow {#intro hidden="true"}
+## Introduction and workflow {id="intro",hidden="true"}
> #### 🪐 Project templates
>
@@ -27,7 +27,7 @@ and share your results with your team. spaCy projects can be used via the new
[`spacy project`](/api/cli#project) command and we provide templates in our
[`projects`](https://github.com/explosion/projects) repo.
-
+
@@ -43,16 +43,34 @@ and experiments, iterate on demos and prototypes and ship your models into
production.
-Manage and version your data
-Create labelled training data
-Visualize and demo your pipelines
-Serve your models and host APIs
-Distributed and parallel training
-Track your experiments and results
-Upload your pipelines to the Hugging Face Hub
+
+ Manage and version your data
+
+
+ Create labelled training data
+
+
+ Visualize and demo your pipelines
+
+
+ Serve your models and host APIs
+
+
+ Distributed and parallel training
+
+
+ Track your experiments and results
+
+
+ Upload your pipelines to the Hugging Face Hub
+
-### 1. Clone a project template {#clone}
+### 1. Clone a project template {id="clone"}
> #### Cloning under the hood
>
@@ -64,7 +82,7 @@ project template and copies the files to a local directory. You can then run the
project, e.g. to train a pipeline and edit the commands and scripts to build
fully custom workflows.
-```cli
+```bash
python -m spacy project clone pipelines/tagger_parser_ud
```
@@ -74,7 +92,7 @@ can specify an optional second argument to define the output directory. The
use the spaCy [`projects`](https://github.com/explosion/projects) repo. You can
also use any private repo you have access to with Git.
-### 2. Fetch the project assets {#assets}
+### 2. Fetch the project assets {id="assets"}
> #### project.yml
>
@@ -94,11 +112,10 @@ also use any private repo you have access to with Git.
Assets are data files your project needs – for example, the training and
evaluation data or pretrained vectors and embeddings to initialize your model
with. Each project template comes with a `project.yml` that defines the assets
-to download and where to put them. The
-[`spacy project assets`](/api/cli#project-assets) will fetch the project assets
-for you:
+to download and where to put them. The [`spacy project assets`](/api/cli#run)
+will fetch the project assets for you:
-```cli
+```bash
$ cd some_example_project
$ python -m spacy project assets
```
@@ -108,7 +125,12 @@ even cloud storage such as GCS and S3. You can also fetch assets using git, by
replacing the `url` string with a `git` block. spaCy will use Git's "sparse
checkout" feature to avoid downloading the whole repository.
-### 3. Run a command {#run}
+Sometimes your project configuration may include large assets that you don't
+necessarily want to download when you run `spacy project assets`. That's why
+assets can be marked as [`extra`](#data-assets-url) - by default, these assets
+are not downloaded. If they should be, run `spacy project assets --extra`.
+
+### 3. Run a command {id="run"}
> #### project.yml
>
@@ -131,7 +153,7 @@ Commands consist of one or more steps and can be run with
[`spacy project run`](/api/cli#project-run). The following will run the command
`preprocess` defined in the `project.yml`:
-```cli
+```bash
$ python -m spacy project run preprocess
```
@@ -144,7 +166,14 @@ skipped. You can also set `--force` to force re-running a command, or `--dry` to
perform a "dry run" and see what would happen (without actually running the
script).
-### 4. Run a workflow {#run-workfow}
+Since spaCy v3.4.2, `spacy projects run` checks your installed dependencies to
+verify that your environment is properly set up and aligns with the project's
+`requirements.txt`, if there is one. If missing or conflicting dependencies are
+detected, a corresponding warning is displayed. If you'd like to disable the
+dependency check, set `check_requirements: false` in your project's
+`project.yml`.
+
+### 4. Run a workflow {id="run-workfow"}
> #### project.yml
>
@@ -164,7 +193,7 @@ pipeline on the converted data and if that's successful, run
installable Python package. The following command runs the workflow named `all`
defined in the `project.yml`, and executes the commands it specifies, in order:
-```cli
+```bash
$ python -m spacy project run all
```
@@ -177,7 +206,7 @@ advanced data pipelines and track your changes in Git, check out the
from a workflow defined in your `project.yml` so you can manage your spaCy
project as a DVC repo.
-### 5. Optional: Push to remote storage {#push}
+### 5. Optional: Push to remote storage {id="push"}
> ```yaml
> ### project.yml
@@ -193,7 +222,7 @@ a remote storage, using protocols like [S3](https://aws.amazon.com/s3/),
you **export** your pipeline packages, **share** work with your team, or **cache
results** to avoid repeating work.
-```cli
+```bash
$ python -m spacy project push
```
@@ -202,9 +231,9 @@ different storages. To download state from a remote storage, you can use the
[`spacy project pull`](/api/cli#project-pull) command. For more details, see the
docs on [remote storage](#remote).
-## Project directory and assets {#directory}
+## Project directory and assets {id="directory"}
-### project.yml {#project-yml}
+### project.yml {id="project-yml"}
The `project.yml` defines the assets a project depends on, like datasets and
pretrained weights, as well as a series of commands that can be run separately
@@ -215,27 +244,58 @@ pipelines.
> #### Tip: Multi-line YAML syntax for long values
>
-> YAML has [multi-line syntax](https://yaml-multiline.info/) that can be
-> helpful for readability with longer values such as project descriptions or
-> commands that take several arguments.
+> YAML has [multi-line syntax](https://yaml-multiline.info/) that can be helpful
+> for readability with longer values such as project descriptions or commands
+> that take several arguments.
```yaml
%%GITHUB_PROJECTS/pipelines/tagger_parser_ud/project.yml
```
-| Section | Description |
-| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `title` | An optional project title used in `--help` message and [auto-generated docs](#custom-docs). |
-| `description` | An optional project description used in [auto-generated docs](#custom-docs). |
-| `vars` | A dictionary of variables that can be referenced in paths, URLs and scripts, just like [`config.cfg` variables](/usage/training#config-interpolation). For example, `${vars.name}` will use the value of the variable `name`. Variables need to be defined in the section `vars`, but can be a nested dict, so you're able to reference `${vars.model.name}`. |
-| `env` | A dictionary of variables, mapped to the names of environment variables that will be read in when running the project. For example, `${env.name}` will use the value of the environment variable defined as `name`. |
-| `directories` | An optional list of [directories](#project-files) that should be created in the project for assets, training outputs, metrics etc. spaCy will make sure that these directories always exist. |
-| `assets` | A list of assets that can be fetched with the [`project assets`](/api/cli#project-assets) command. `url` defines a URL or local path, `dest` is the destination file relative to the project directory, and an optional `checksum` ensures that an error is raised if the file's checksum doesn't match. Instead of `url`, you can also provide a `git` block with the keys `repo`, `branch` and `path`, to download from a Git repo. |
-| `workflows` | A dictionary of workflow names, mapped to a list of command names, to execute in order. Workflows can be run with the [`project run`](/api/cli#project-run) command. |
-| `commands` | A list of named commands. A command can define an optional help message (shown in the CLI when the user adds `--help`) and the `script`, a list of commands to run. The `deps` and `outputs` let you define the created file the command depends on and produces, respectively. This lets spaCy determine whether a command needs to be re-run because its dependencies or outputs changed. Commands can be run as part of a workflow, or separately with the [`project run`](/api/cli#project-run) command. |
-| `spacy_version` | Optional spaCy version range like `>=3.0.0,<3.1.0` that the project is compatible with. If it's loaded with an incompatible version, an error is raised when the project is loaded. |
+> #### Tip: Overriding variables on the CLI
+>
+> If you want to override one or more variables on the CLI and are not already
+> specifying a project directory, you need to add `.` as a placeholder:
+>
+> ```
+> python -m spacy project run test . --vars.foo bar
+> ```
-### Data assets {#data-assets}
+> #### Tip: Environment Variables
+>
+> Commands in a project file are not executed in a shell, so they don't have
+> direct access to environment variables. But you can insert environment
+> variables using the `env` dictionary to make values available for
+> interpolation, just like values in `vars`. Here's an example `env` dict that
+> makes `$PATH` available as `ENV_PATH`:
+>
+> ```yaml
+> env:
+> ENV_PATH: PATH
+> ```
+>
+> This can be used in a project command like so:
+>
+> ```yaml
+> - name: 'echo-path'
+> script:
+> - 'echo ${env.ENV_PATH}'
+> ```
+
+| Section | Description |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `title` | An optional project title used in `--help` message and [auto-generated docs](#custom-docs). |
+| `description` | An optional project description used in [auto-generated docs](#custom-docs). |
+| `vars` | A dictionary of variables that can be referenced in paths, URLs and scripts and overriden on the CLI, just like [`config.cfg` variables](/usage/training#config-interpolation). For example, `${vars.name}` will use the value of the variable `name`. Variables need to be defined in the section `vars`, but can be a nested dict, so you're able to reference `${vars.model.name}`. |
+| `env` | A dictionary of variables, mapped to the names of environment variables that will be read in when running the project. For example, `${env.name}` will use the value of the environment variable defined as `name`. |
+| `directories` | An optional list of [directories](#project-files) that should be created in the project for assets, training outputs, metrics etc. spaCy will make sure that these directories always exist. |
+| `assets` | A list of assets that can be fetched with the [`project assets`](/api/cli#project-assets) command. `url` defines a URL or local path, `dest` is the destination file relative to the project directory, and an optional `checksum` ensures that an error is raised if the file's checksum doesn't match. Instead of `url`, you can also provide a `git` block with the keys `repo`, `branch` and `path`, to download from a Git repo. |
+| `workflows` | A dictionary of workflow names, mapped to a list of command names, to execute in order. Workflows can be run with the [`project run`](/api/cli#project-run) command. |
+| `commands` | A list of named commands. A command can define an optional help message (shown in the CLI when the user adds `--help`) and the `script`, a list of commands to run. The `deps` and `outputs` let you define the created file the command depends on and produces, respectively. This lets spaCy determine whether a command needs to be re-run because its dependencies or outputs changed. Commands can be run as part of a workflow, or separately with the [`project run`](/api/cli#project-run) command. |
+| `spacy_version` | Optional spaCy version range like `>=3.0.0,<3.1.0` that the project is compatible with. If it's loaded with an incompatible version, an error is raised when the project is loaded. |
+| `check_requirements` 3.4.2 | A flag determining whether to verify that the installed dependencies align with the project's `requirements.txt`. Defaults to `true`. |
+
+### Data assets {id="data-assets"}
Assets are any files that your project might need, like training and development
corpora or pretrained weights for initializing your model. Assets are defined in
@@ -246,7 +306,7 @@ Asset URLs can be a number of different **protocols**: HTTP, HTTPS, FTP, SSH,
and even **cloud storage** such as GCS and S3. You can also download assets from
a **Git repo** instead.
-#### Downloading from a URL or cloud storage {#data-assets-url}
+#### Downloading from a URL or cloud storage {id="data-assets-url"}
Under the hood, spaCy uses the
[`smart-open`](https://github.com/RaRe-Technologies/smart_open) library so you
@@ -261,8 +321,9 @@ dependencies to use certain protocols.
> - dest: 'assets/training.spacy'
> url: 'https://example.com/data.spacy'
> checksum: '63373dd656daa1fd3043ce166a59474c'
-> # Download from Google Cloud Storage bucket
+> # Optional download from Google Cloud Storage bucket
> - dest: 'assets/development.spacy'
+> extra: True
> url: 'gs://your-bucket/corpora'
> checksum: '5113dc04e03f079525edd8df3f4f39e3'
> ```
@@ -270,11 +331,12 @@ dependencies to use certain protocols.
| Name | Description |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dest` | The destination path to save the downloaded asset to (relative to the project directory), including the file name. |
+| `extra` | Optional flag determining whether this asset is downloaded only if `spacy project assets` is run with `--extra`. `False` by default. |
| `url` | The URL to download from, using the respective protocol. |
| `checksum` | Optional checksum of the file. If provided, it will be used to verify that the file matches and downloads will be skipped if a local file with the same checksum already exists. |
| `description` | Optional asset description, used in [auto-generated docs](#custom-docs). |
-#### Downloading from a Git repo {#data-assets-git}
+#### Downloading from a Git repo {id="data-assets-git"}
If a `git` block is provided, the asset is downloaded from the given Git
repository. You can download from any repo that you have access to. Under the
@@ -294,14 +356,14 @@ files you need and not the whole repo.
> description: 'The training data (5000 examples)'
> ```
-| Name | Description |
-| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `dest` | The destination path to save the downloaded asset to (relative to the project directory), including the file name. |
+| Name | Description |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dest` | The destination path to save the downloaded asset to (relative to the project directory), including the file name. |
| `git` | `repo`: The URL of the repo to download from. `path`: Path of the file or directory to download, relative to the repo root. "" specifies the root directory. `branch`: The branch to download from. Defaults to `"master"`. |
-| `checksum` | Optional checksum of the file. If provided, it will be used to verify that the file matches and downloads will be skipped if a local file with the same checksum already exists. |
-| `description` | Optional asset description, used in [auto-generated docs](#custom-docs). |
+| `checksum` | Optional checksum of the file. If provided, it will be used to verify that the file matches and downloads will be skipped if a local file with the same checksum already exists. |
+| `description` | Optional asset description, used in [auto-generated docs](#custom-docs). |
-#### Working with private assets {#data-asets-private}
+#### Working with private assets {id="data-asets-private"}
> #### project.yml
>
@@ -321,7 +383,7 @@ directory themselves. The [`project assets`](/api/cli#project-assets) command
will alert you about missing files and mismatched checksums, so you can ensure
that others are running your project with the same data.
-### Dependencies and outputs {#deps-outputs}
+### Dependencies and outputs {id="deps-outputs"}
Each command defined in the `project.yml` can optionally define a list of
dependencies and outputs. These are the files the command requires and creates.
@@ -330,9 +392,8 @@ For example, a command for training a pipeline may depend on a
it will export a directory `model-best`, which you can then re-use in other
commands.
-
-```yaml
-### project.yml
+{/* prettier-ignore */}
+```yaml {title="project.yml"}
commands:
- name: train
help: 'Train a spaCy pipeline using the specified corpus and config'
@@ -371,7 +432,7 @@ If you're planning on integrating your spaCy project with DVC, you can also use
`outputs_no_cache` instead of `outputs` to define outputs that won't be cached
or tracked.
-### Files and directory structure {#project-files}
+### Files and directory structure {id="project-files"}
The `project.yml` can define a list of `directories` that should be created
within a project – for instance, `assets`, `training`, `corpus` and so on. spaCy
@@ -383,13 +444,12 @@ directory:
> #### project.yml
>
->
+> {/* prettier-ignore */}
> ```yaml
> directories: ['assets', 'configs', 'corpus', 'metas', 'metrics', 'notebooks', 'packages', 'scripts', 'training']
> ```
-```yaml
-### Example project directory
+```yaml {title="Example project directory"}
├── project.yml # the project settings
├── project.lock # lockfile that tracks inputs/outputs
├── assets/ # downloaded data assets
@@ -411,7 +471,7 @@ the only file that's required for a project is the `project.yml`.
---
-## Custom scripts and projects {#custom}
+## Custom scripts and projects {id="custom"}
The `project.yml` lets you define any custom commands and run them as part of
your training, evaluation or deployment workflows. The `script` section defines
@@ -423,8 +483,7 @@ calls into [`pytest`](https://docs.pytest.org/en/latest/), runs your tests and
uses [`pytest-html`](https://github.com/pytest-dev/pytest-html) to export a test
report:
-```yaml
-### project.yml
+```yaml {title="project.yml"}
commands:
- name: test
help: 'Test the trained pipeline'
@@ -444,7 +503,7 @@ Setting `no_skip: true` means that the command will always run, even if the
dependencies (the trained pipeline) haven't changed. This makes sense here,
because you typically don't want to skip your tests.
-### Writing custom scripts {#custom-scripts}
+### Writing custom scripts {id="custom-scripts"}
Your project commands can include any custom scripts – essentially, anything you
can run from the command line. Here's an example of a custom script that uses
@@ -460,8 +519,7 @@ that you can define via your `project.yml`:
> types. For instance, `batch_size: int` means that the value provided via the
> command line is converted to an integer.
-```python
-### scripts/custom_evaluation.py
+```python {title="scripts/custom_evaluation.py"}
import typer
def custom_evaluation(batch_size: int = 128, model_path: str, data_path: str):
@@ -487,9 +545,8 @@ override settings on the command line – for example using `--vars.batch_size`.
> everything with the same Python (not some other Python installed on your
> system). It also normalizes references to `python3`, `pip3` and `pip`.
-
-```yaml
-### project.yml
+{/* prettier-ignore */}
+```yaml {title="project.yml"}
vars:
batch_size: 128
@@ -513,8 +570,7 @@ settings on the command line and passing through system-level settings.
> BATCH_SIZE=128 python -m spacy project run evaluate
> ```
-```yaml
-### project.yml
+```yaml {title="project.yml"}
env:
batch_size: BATCH_SIZE
gpu_id: GPU_ID
@@ -525,14 +581,14 @@ commands:
- 'python scripts/custom_evaluation.py ${env.batch_size}'
```
-### Documenting your project {#custom-docs}
+### Documenting your project {id="custom-docs"}
> #### Readme Example
>
> For more examples, see the [`projects`](https://github.com/explosion/projects)
> repo.
>
-> 
+> 
When your custom project is ready and you want to share it with others, you can
use the [`spacy project document`](/api/cli#project-document) command to
@@ -542,7 +598,7 @@ in the project and include details on how to run the project, as well as links
to the relevant spaCy documentation to make it easy for others to get started
using your project.
-```cli
+```bash
$ python -m spacy project document --output README.md
```
@@ -556,18 +612,18 @@ up to date.
Note that the contents of an existing file will be **replaced** if no existing
auto-generated docs are found. If you want spaCy to ignore a file and not update
-it, you can add the comment marker `` anywhere in
+it, you can add the comment marker `{/* SPACY PROJECT: IGNORE */}` anywhere in
your markup.
-### Cloning from your own repo {#custom-repo}
+### Cloning from your own repo {id="custom-repo"}
The [`spacy project clone`](/api/cli#project-clone) command lets you customize
the repo to clone from using the `--repo` option. It calls into `git`, so you'll
be able to clone from any repo that you have access to, including private repos.
-```cli
+```bash
python -m spacy project clone your_project --repo https://github.com/you/repo
```
@@ -588,7 +644,7 @@ projects.
-## Remote Storage {#remote}
+## Remote Storage {id="remote"}
You can persist your project outputs to a remote storage using the
[`project push`](/api/cli#project-push) command. This can help you **export**
@@ -599,25 +655,24 @@ locally.
You can list one or more remotes in the `remotes` section of your
[`project.yml`](#project-yml) by mapping a string name to the URL of the
-storage. Under the hood, spaCy uses the
-[`smart-open`](https://github.com/RaRe-Technologies/smart_open) library to
-communicate with the remote storages, so you can use any protocol that
-`smart-open` supports, including [S3](https://aws.amazon.com/s3/),
-[Google Cloud Storage](https://cloud.google.com/storage), SSH and more, although
-you may need to install extra dependencies to use certain protocols.
+storage. Under the hood, spaCy uses
+[`Pathy`](https://github.com/justindujardin/pathy) to communicate with the
+remote storages, so you can use any protocol that `Pathy` supports, including
+[S3](https://aws.amazon.com/s3/),
+[Google Cloud Storage](https://cloud.google.com/storage), and the local
+filesystem, although you may need to install extra dependencies to use certain
+protocols.
> #### Example
>
-> ```cli
+> ```bash
> $ python -m spacy project pull local
> ```
-```yaml
-### project.yml
+```yaml {title="project.yml"}
remotes:
default: 's3://my-spacy-bucket'
local: '/mnt/scratch/cache'
- stuff: 'ssh://myserver.example.com/whatever'
```
@@ -629,9 +684,9 @@ according to a hash of the command string and the command's dependencies.
Finally, within those directories are files, named according to an MD5 hash of
their contents.
-
+{/* TODO: update with actual real example? */}
-
+{/* prettier-ignore */}
```yaml
└── urlencoded_file_path # Path of original file
├── some_command_hash # Hash of command you ran
@@ -645,8 +700,7 @@ their contents.
For instance, let's say you had the following command in your `project.yml`:
-```yaml
-### project.yml
+```yaml {title="project.yml"}
- name: train
help: 'Train a spaCy pipeline using the specified corpus and config'
script:
@@ -675,7 +729,7 @@ execution context of your output. It would then compute an MD5 hash of the
`training/model-best` directory, and use those three pieces of information to
construct the storage URL.
-```cli
+```bash
$ python -m spacy project run train
$ python -m spacy project push
```
@@ -696,9 +750,12 @@ state, and you don't have to come up with names or version numbers. However,
it's up to you to manage the size of your remote storage, and to remove files
that are no longer relevant to you.
-## Integrations {#integrations}
+## Integrations {id="integrations"}
-### Data Version Control (DVC) {#dvc}
+{
Data Version Control (DVC)
+
+
+
}
Data assets like training corpora or pretrained weights are at the core of any
NLP project, but they're often difficult to manage: you can't just check them
@@ -743,8 +800,8 @@ can then manage your spaCy project like any other DVC project, run
and [`dvc repro`](https://dvc.org/doc/command-reference/repro) to reproduce the
workflow or individual commands.
-```cli
-$ python -m spacy project dvc [workflow_name]
+```bash
+$ python -m spacy project dvc [project_dir] [workflow_name]
```
@@ -756,13 +813,14 @@ workflows, but only one can be tracked by DVC.
-
+{/* { TODO: } */}
---
-### Prodigy {#prodigy}
+{
Prodigy
+
+
+
}
[Prodigy](https://prodi.gy) is a modern annotation tool for creating training
data for machine learning models, developed by us. It integrates with spaCy
@@ -787,13 +845,12 @@ collected with Prodigy and training a spaCy pipeline:
> #### Example usage
>
-> ```cli
+> ```bash
> $ python -m spacy project run all
> ```
-
-```yaml
-### project.yml
+{/* prettier-ignore */}
+```yaml {title="project.yml"}
vars:
prodigy:
train_dataset: "fashion_brands_training"
@@ -825,7 +882,11 @@ commands:
> #### Example train curve output
>
-> [](https://prodi.gy/docs/recipes#train-curve)
+> src="/images/prodigy_train_curve.jpg"
+> href="https://prodi.gy/docs/recipes#train-curve"
+> alt="Screenshot of train curve terminal output"
+> />
The [`train-curve`](https://prodi.gy/docs/recipes#train-curve) recipe is another
cool workflow you can include in your project. It will run the training with
@@ -833,9 +894,8 @@ different portions of the data, e.g. 25%, 50%, 75% and 100%. As a rule of thumb,
if accuracy increases in the last segment, this could indicate that collecting
more annotations of the same type might improve the model further.
-
-```yaml
-### project.yml (excerpt)
+{/* prettier-ignore */}
+```yaml {title="project.yml (excerpt)"}
- name: "train_curve"
help: "Train the model with Prodigy by using different portions of training examples to evaluate if more annotations can potentially improve the performance"
script:
@@ -864,7 +924,10 @@ improve performance.
---
-### Streamlit {#streamlit}
+{
Streamlit
+
+
+
}
[Streamlit](https://streamlit.io) is a Python framework for building interactive
data apps. The [`spacy-streamlit`](https://github.com/explosion/spacy-streamlit)
@@ -872,7 +935,7 @@ package helps you integrate spaCy visualizations into your Streamlit apps and
quickly spin up demos to explore your pipelines interactively. It includes a
full embedded visualizer, as well as individual components.
-
+{/* TODO: update once version is stable */}
> #### Installation
>
@@ -880,7 +943,7 @@ full embedded visualizer, as well as individual components.
> $ pip install spacy-streamlit --pre
> ```
-
+
Using [`spacy-streamlit`](https://github.com/explosion/spacy-streamlit), your
projects can easily define their own scripts that spin up an interactive
@@ -897,13 +960,12 @@ and explore your own custom trained pipelines.
> #### Example usage
>
-> ```cli
+> ```bash
> $ python -m spacy project run visualize
> ```
-
-```yaml
-### project.yml
+{/* prettier-ignore */}
+```yaml {title="project.yml"}
commands:
- name: visualize
help: "Visualize the pipeline's output interactively using Streamlit"
@@ -923,7 +985,10 @@ https://github.com/explosion/projects/blob/v3/integrations/streamlit/scripts/vis
---
-### FastAPI {#fastapi}
+{
FastAPI
+
+
+
}
[FastAPI](https://fastapi.tiangolo.com/) is a modern high-performance framework
for building REST APIs with Python, based on Python
@@ -942,13 +1007,12 @@ query your API from Python and JavaScript (Vanilla JS and React).
> #### Example usage
>
-> ```cli
+> ```bash
> $ python -m spacy project run serve
> ```
-
-```yaml
-### project.yml
+{/* prettier-ignore */}
+```yaml {title="project.yml"}
- name: "serve"
help: "Serve the models via a FastAPI REST API using the given host and port"
script:
@@ -970,55 +1034,10 @@ https://github.com/explosion/projects/blob/v3/integrations/fastapi/scripts/main.
---
-### Ray {#ray}
+{
Weights & Biases
-> #### Installation
->
-> ```cli
-> $ pip install -U %%SPACY_PKG_NAME[ray]%%SPACY_PKG_FLAGS
-> # Check that the CLI is registered
-> $ python -m spacy ray --help
-> ```
-
-[Ray](https://ray.io/) is a fast and simple framework for building and running
-**distributed applications**. You can use Ray for parallel and distributed
-training with spaCy via our lightweight
-[`spacy-ray`](https://github.com/explosion/spacy-ray) extension package. If the
-package is installed in the same environment as spaCy, it will automatically add
-[`spacy ray`](/api/cli#ray) commands to your spaCy CLI. See the usage guide on
-[parallel training](/usage/training#parallel-training) for more details on how
-it works under the hood.
-
-
-
-Get started with parallel training using our project template. It trains a
-simple model on a Universal Dependencies Treebank and lets you parallelize the
-training with Ray.
-
-
-
-You can integrate [`spacy ray train`](/api/cli#ray-train) into your
-`project.yml` just like the regular training command and pass it the config, and
-optional output directory or remote storage URL and config overrides if needed.
-
-
-```yaml
-### project.yml
-commands:
- - name: "ray"
- help: "Train a model via parallel training with Ray"
- script:
- - "python -m spacy ray train configs/config.cfg -o training/ --paths.train corpus/train.spacy --paths.dev corpus/dev.spacy"
- deps:
- - "corpus/train.spacy"
- - "corpus/dev.spacy"
- outputs:
- - "training/model-best"
-```
-
----
-
-### Weights & Biases {#wandb}
+
+
}
[Weights & Biases](https://www.wandb.com/) is a popular platform for experiment
tracking. spaCy integrates with it out-of-the-box via the
@@ -1040,9 +1059,9 @@ and you'll be able to see the impact it has on your results.
> model_log_interval = 1000
> ```
-
+
-
+
@@ -1056,7 +1075,10 @@ logging the results.
---
-### Hugging Face Hub {#huggingface_hub}
+{
Hugging Face Hub
+
+
+
}
The [Hugging Face Hub](https://huggingface.co/) lets you upload models and share
them with others. It hosts models as Git-based repositories which are storage
@@ -1069,7 +1091,7 @@ it's installed.
> #### Installation
>
-> ```cli
+> ```bash
> $ pip install spacy-huggingface-hub
> # Check that the CLI is registered
> $ python -m spacy huggingface-hub --help
@@ -1082,7 +1104,7 @@ package, including the auto-generated pretty `README.md` and the model details
available in the `meta.json`. For examples, check out the
[spaCy pipelines](https://huggingface.co/spacy) we've uploaded.
-```cli
+```bash
$ huggingface-cli login
$ python -m spacy package ./en_ner_fashion ./output --build wheel
$ cd ./output/en_ner_fashion-0.0.0/dist
@@ -1093,16 +1115,15 @@ After uploading, you will see the live URL of your pipeline packages, as well as
the direct URL to the model wheel you can install via `pip install`. You'll also
be able to test your pipeline interactively from your browser:
-
+
In your `project.yml`, you can add a command that uploads your trained and
packaged pipeline to the hub. You can either run this as a manual step, or
automatically as part of a workflow. Make sure to set `--build wheel` when
running `spacy package` to build a wheel file for your pipeline package.
-
-```yaml
-### project.yml
+{/* prettier-ignore */}
+```yaml {title="project.yml"}
- name: "push_to_hub"
help: "Upload the trained model to the Hugging Face Hub"
script:
diff --git a/website/docs/usage/rule-based-matching.md b/website/docs/usage/rule-based-matching.mdx
similarity index 84%
rename from website/docs/usage/rule-based-matching.md
rename to website/docs/usage/rule-based-matching.mdx
index 74bb10304..08d2b3b91 100644
--- a/website/docs/usage/rule-based-matching.md
+++ b/website/docs/usage/rule-based-matching.mdx
@@ -6,6 +6,7 @@ menu:
- ['Phrase Matcher', 'phrasematcher']
- ['Dependency Matcher', 'dependencymatcher']
- ['Entity Ruler', 'entityruler']
+ - ['Span Ruler', 'spanruler']
- ['Models & Rules', 'models-rules']
---
@@ -59,7 +60,7 @@ another token that's at least 10 characters long.
-## Token-based matching {#matcher}
+## Token-based matching {id="matcher"}
spaCy features a rule-matching engine, the [`Matcher`](/api/matcher), that
operates over tokens, similar to regular expressions. The rules can refer to
@@ -71,7 +72,7 @@ To match large terminology lists, you can use the
[`PhraseMatcher`](/api/phrasematcher), which accepts `Doc` objects as match
patterns.
-### Adding patterns {#adding-patterns}
+### Adding patterns {id="adding-patterns"}
Let's say we want to enable spaCy to find a combination of three tokens:
@@ -101,8 +102,7 @@ First, we initialize the `Matcher` with a vocab. The matcher must always share
the same vocab with the documents it will operate on. We can now call
[`matcher.add()`](/api/matcher#add) with an ID and a list of patterns.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy.matcher import Matcher
@@ -152,28 +152,29 @@ merge _some_ patterns into one token, while adding entity labels for other
pattern types. You shouldn't have to create different matchers for each of those
processes.
-#### Available token attributes {#adding-patterns-attributes}
+#### Available token attributes {id="adding-patterns-attributes"}
The available token pattern keys correspond to a number of
[`Token` attributes](/api/token#attributes). The supported attributes for
rule-based matching are:
-| Attribute | Description |
-| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ORTH` | The exact verbatim text of a token. ~~str~~ |
-| `TEXT` 2.1 | The exact verbatim text of a token. ~~str~~ |
-| `LOWER` | The lowercase form of the token text. ~~str~~ |
-| `LENGTH` | The length of the token text. ~~int~~ |
-| `IS_ALPHA`, `IS_ASCII`, `IS_DIGIT` | Token text consists of alphabetic characters, ASCII characters, digits. ~~bool~~ |
-| `IS_LOWER`, `IS_UPPER`, `IS_TITLE` | Token text is in lowercase, uppercase, titlecase. ~~bool~~ |
-| `IS_PUNCT`, `IS_SPACE`, `IS_STOP` | Token is punctuation, whitespace, stop word. ~~bool~~ |
-| `IS_SENT_START` | Token is start of sentence. ~~bool~~ |
-| `LIKE_NUM`, `LIKE_URL`, `LIKE_EMAIL` | Token text resembles a number, URL, email. ~~bool~~ |
-| `SPACY` | Token has a trailing space. ~~bool~~ |
-| `POS`, `TAG`, `MORPH`, `DEP`, `LEMMA`, `SHAPE` | The token's simple and extended part-of-speech tag, morphological analysis, dependency label, lemma, shape. Note that the values of these attributes are case-sensitive. For a list of available part-of-speech tags and dependency labels, see the [Annotation Specifications](/api/annotation). ~~str~~ |
-| `ENT_TYPE` | The token's entity label. ~~str~~ |
-| `_` 2.1 | Properties in [custom extension attributes](/usage/processing-pipelines#custom-components-attributes). ~~Dict[str, Any]~~ |
-| `OP` | [Operator or quantifier](#quantifiers) to determine how often to match a token pattern. ~~str~~ |
+| Attribute | Description |
+| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ORTH` | The exact verbatim text of a token. ~~str~~ |
+| `TEXT` | The exact verbatim text of a token. ~~str~~ |
+| `NORM` | The normalized form of the token text. ~~str~~ |
+| `LOWER` | The lowercase form of the token text. ~~str~~ |
+| `LENGTH` | The length of the token text. ~~int~~ |
+| `IS_ALPHA`, `IS_ASCII`, `IS_DIGIT` | Token text consists of alphabetic characters, ASCII characters, digits. ~~bool~~ |
+| `IS_LOWER`, `IS_UPPER`, `IS_TITLE` | Token text is in lowercase, uppercase, titlecase. ~~bool~~ |
+| `IS_PUNCT`, `IS_SPACE`, `IS_STOP` | Token is punctuation, whitespace, stop word. ~~bool~~ |
+| `IS_SENT_START` | Token is start of sentence. ~~bool~~ |
+| `LIKE_NUM`, `LIKE_URL`, `LIKE_EMAIL` | Token text resembles a number, URL, email. ~~bool~~ |
+| `SPACY` | Token has a trailing space. ~~bool~~ |
+| `POS`, `TAG`, `MORPH`, `DEP`, `LEMMA`, `SHAPE` | The token's simple and extended part-of-speech tag, morphological analysis, dependency label, lemma, shape. Note that the values of these attributes are case-sensitive. For a list of available part-of-speech tags and dependency labels, see the [Annotation Specifications](/api/annotation). ~~str~~ |
+| `ENT_TYPE` | The token's entity label. ~~str~~ |
+| `_` | Properties in [custom extension attributes](/usage/processing-pipelines#custom-components-attributes). ~~Dict[str, Any]~~ |
+| `OP` | [Operator or quantifier](#quantifiers) to determine how often to match a token pattern. ~~str~~ |
@@ -206,7 +207,11 @@ you need to describe fields like this.
-[](https://explosion.ai/demos/matcher)
+
The [Matcher Explorer](https://explosion.ai/demos/matcher) lets you test the
rule-based `Matcher` by creating token patterns interactively and running them
@@ -216,7 +221,7 @@ spaCy processes your text – and why your pattern matches, or why it doesn't.
-#### Extended pattern syntax and attributes {#adding-patterns-attributes-extended new="2.1"}
+#### Extended pattern syntax and attributes {id="adding-patterns-attributes-extended",version="2.1"}
Instead of mapping to a single value, token patterns can also map to a
**dictionary of properties**. For example, to specify that the value of a lemma
@@ -249,7 +254,7 @@ following rich comparison attributes are available:
| `INTERSECTS` | Attribute value (for `MORPH` or custom list attributes) has a non-empty intersection with a list. ~~Any~~ |
| `==`, `>=`, `<=`, `>`, `<` | Attribute value is equal, greater or equal, smaller or equal, greater or smaller. ~~Union[int, float]~~ |
-#### Regular expressions {#regex new="2.1"}
+#### Regular expressions {id="regex",version="2.1"}
In some cases, only matching tokens and token attributes isn't enough – for
example, you might want to match different spellings of a word, without having
@@ -285,7 +290,7 @@ token. If you need to match on the whole text instead, see the details on
-##### Matching regular expressions on the full text {#regex-text}
+##### Matching regular expressions on the full text {id="regex-text"}
If your expressions apply to multiple tokens, a simple solution is to match on
the `doc.text` with `re.finditer` and use the
@@ -299,8 +304,7 @@ more valid tokens, `Doc.char_span` returns `None`.
> `"USA"` is a single token and `Span` objects are **sequences of tokens**. So
> `"US"` cannot be its own span, because it does not end on a token boundary.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
import re
@@ -347,8 +351,7 @@ the (white)space tokens are split on. That hopefully shouldn't happen, though,
because it'd mean your regex is producing matches with leading or trailing
whitespace.
-```python
-### {highlight="5-8"}
+```python {highlight="5-8"}
span = doc.char_span(start, end)
if span is not None:
print("Found match:", span.text)
@@ -362,9 +365,49 @@ else:
+#### Fuzzy matching {id="fuzzy", version="3.5"}
+
+Fuzzy matching allows you to match tokens with alternate spellings, typos, etc.
+without specifying every possible variant.
+
+```python
+# Matches "favourite", "favorites", "gavorite", "theatre", "theatr", ...
+pattern = [{"TEXT": {"FUZZY": "favorite"}},
+ {"TEXT": {"FUZZY": "theater"}}]
+```
+
+The `FUZZY` attribute allows fuzzy matches for any attribute string value,
+including custom attributes. Just like `REGEX`, it always needs to be applied to
+an attribute like `TEXT` or `LOWER`. By default `FUZZY` allows a Levenshtein
+edit distance of at least 2 and up to 30% of the pattern string length. Using
+the more specific attributes `FUZZY1`..`FUZZY9` you can specify the maximum
+allowed edit distance directly.
+
+```python
+# Match lowercase with fuzzy matching (allows 3 edits)
+pattern = [{"LOWER": {"FUZZY": "definitely"}}]
+
+# Match custom attribute values with fuzzy matching (allows 3 edits)
+pattern = [{"_": {"country": {"FUZZY": "Kyrgyzstan"}}}]
+
+# Match with exact Levenshtein edit distance limits (allows 4 edits)
+pattern = [{"_": {"country": {"FUZZY4": "Kyrgyzstan"}}}]
+```
+
+#### Regex and fuzzy matching with lists {id="regex-fuzzy-lists", version="3.5"}
+
+Starting in spaCy v3.5, both `REGEX` and `FUZZY` can be combined with the
+attributes `IN` and `NOT_IN`:
+
+```python
+pattern = [{"TEXT": {"FUZZY": {"IN": ["awesome", "cool", "wonderful"]}}}]
+
+pattern = [{"TEXT": {"REGEX": {"NOT_IN": ["^awe(some)?$", "^wonder(ful)?"]}}}]
+```
+
---
-#### Operators and quantifiers {#quantifiers}
+#### Operators and quantifiers {id="quantifiers"}
The matcher also lets you use quantifiers, specified as the `'OP'` key.
Quantifiers let you define sequences of tokens to be matched, e.g. one or more
@@ -372,12 +415,16 @@ punctuation marks, or specify optional tokens. Note that there are no nested or
scoped quantifiers – instead, you can build those behaviors with `on_match`
callbacks.
-| OP | Description |
-| --- | ---------------------------------------------------------------- |
-| `!` | Negate the pattern, by requiring it to match exactly 0 times. |
-| `?` | Make the pattern optional, by allowing it to match 0 or 1 times. |
-| `+` | Require the pattern to match 1 or more times. |
-| `*` | Allow the pattern to match zero or more times. |
+| OP | Description |
+| ------- | ---------------------------------------------------------------------- |
+| `!` | Negate the pattern, by requiring it to match exactly 0 times. |
+| `?` | Make the pattern optional, by allowing it to match 0 or 1 times. |
+| `+` | Require the pattern to match 1 or more times. |
+| `*` | Allow the pattern to match zero or more times. |
+| `{n}` | Require the pattern to match exactly _n_ times. |
+| `{n,m}` | Require the pattern to match at least _n_ but not more than _m_ times. |
+| `{n,}` | Require the pattern to match at least _n_ times. |
+| `{,m}` | Require the pattern to match at most _m_ times. |
> #### Example
>
@@ -396,28 +443,28 @@ This quirk in the semantics is corrected in spaCy v2.1.0.
-#### Using wildcard token patterns {#adding-patterns-wildcard new="2"}
+#### Using wildcard token patterns {id="adding-patterns-wildcard",version="2"}
While the token attributes offer many options to write highly specific patterns,
you can also use an empty dictionary, `{}` as a wildcard representing **any
token**. This is useful if you know the context of what you're trying to match,
but very little about the specific token and its characters. For example, let's
say you're trying to extract people's user names from your data. All you know is
-that they are listed as "User name: {username}". The name itself may contain any
-character, but no whitespace – so you'll know it will be handled as one token.
+that they are listed as "User name: \{username\}". The name itself may contain
+any character, but no whitespace – so you'll know it will be handled as one
+token.
```python
[{"ORTH": "User"}, {"ORTH": "name"}, {"ORTH": ":"}, {}]
```
-#### Validating and debugging patterns {#pattern-validation new="2.1"}
+#### Validating and debugging patterns {id="pattern-validation",version="2.1"}
The `Matcher` can validate patterns against a JSON schema with the option
`validate=True`. This is useful for debugging patterns during development, in
particular for catching unsupported attributes.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy.matcher import Matcher
@@ -433,7 +480,7 @@ matcher.add("HelloWorld", [pattern])
```
-### Adding on_match rules {#on_match}
+### Adding on_match rules {id="on_match"}
To move on to a more realistic example, let's say you're working with a large
corpus of blog articles, and you want to match all mentions of "Google I/O"
@@ -441,8 +488,7 @@ corpus of blog articles, and you want to match all mentions of "Google I/O"
match on the uppercase versions, avoiding matches with phrases such as "Google
i/o".
-```python
-### {executable="true"}
+```python {executable="true"}
from spacy.lang.en import English
from spacy.matcher import Matcher
from spacy.tokens import Span
@@ -505,7 +551,7 @@ you prefer.
| `i` | Index of the current match (`matches[i`]). ~~int~~ |
| `matches` | A list of `(match_id, start, end)` tuples, describing the matches. A match tuple describes a span `doc[start:end`]. ~~List[Tuple[int, int int]]~~ |
-### Creating spans from matches {#matcher-spans}
+### Creating spans from matches {id="matcher-spans"}
Creating [`Span`](/api/span) objects from the returned matches is a very common
use case. spaCy makes this easy by giving you access to the `start` and `end`
@@ -514,8 +560,7 @@ label. As of spaCy v3.0, you can also set `as_spans=True` when calling the
matcher on a `Doc`, which will return a list of [`Span`](/api/span) objects
using the `match_id` as the span label.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy.matcher import Matcher
from spacy.tokens import Span
@@ -538,7 +583,7 @@ for span in matches:
print(span.text, span.label_)
```
-### Using custom pipeline components {#matcher-pipeline}
+### Using custom pipeline components {id="matcher-pipeline"}
Let's say your data also contains some annoying pre-processing artifacts, like
leftover HTML line breaks (e.g. ` ` or ` `). To make your text easier to
@@ -549,8 +594,7 @@ process the text. You can achieve this by adding a
that's called on each `Doc` object, merges the leftover HTML spans and sets an
attribute `bad_html` on the token.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy.language import Language
from spacy.matcher import Matcher
@@ -616,7 +660,7 @@ and **extension attributes**, see the
-### Example: Using linguistic annotations {#example1}
+### Example: Using linguistic annotations {id="example1"}
Let's say you're analyzing user comments and you want to find out what people
are saying about Facebook. You want to start off by finding adjectives following
@@ -645,8 +689,7 @@ calculate the start and end of the matched span within the sentence. Using
displaCy in ["manual" mode](/usage/visualizers#manual-usage) lets you pass in a
list of dictionaries containing the text and entities to render.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy import displacy
from spacy.matcher import Matcher
@@ -682,7 +725,7 @@ matches = matcher(doc)
displacy.render(matched_sents, style="ent", manual=True)
```
-### Example: Phone numbers {#example2}
+### Example: Phone numbers {id="example2"}
Phone numbers can have many different formats and matching them is often tricky.
During tokenization, spaCy will leave sequences of numbers intact and only split
@@ -717,8 +760,7 @@ set of rules like this is often better than training a model. It'll produce more
predictable results, is much easier to modify and extend, and doesn't require
any training data – only a set of test cases.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy.matcher import Matcher
@@ -736,7 +778,7 @@ for match_id, start, end in matches:
print(span.text)
```
-### Example: Hashtags and emoji on social media {#example3}
+### Example: Hashtags and emoji on social media {id="example3"}
Social media posts, especially tweets, can be difficult to work with. They're
very short and often contain various emoji and hashtags. By only looking at the
@@ -766,8 +808,7 @@ that you can create a pattern for one or more emoji tokens. Valid hashtags
usually consist of a `#`, plus a sequence of ASCII characters with no
whitespace, making them easy to match as well.
-```python
-### {executable="true"}
+```python {executable="true"}
from spacy.lang.en import English
from spacy.matcher import Matcher
@@ -837,8 +878,7 @@ To label the hashtags, we can use a
[custom attribute](/usage/processing-pipelines#custom-components-attributes) set
on the respective token:
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy.matcher import Matcher
from spacy.tokens import Token
@@ -868,17 +908,16 @@ for token in doc:
print(token.text, token._.is_hashtag)
```
-## Efficient phrase matching {#phrasematcher}
+## Efficient phrase matching {id="phrasematcher"}
If you need to match large terminology lists, you can also use the
[`PhraseMatcher`](/api/phrasematcher) and create [`Doc`](/api/doc) objects
instead of token patterns, which is much more efficient overall. The `Doc`
patterns can contain single or multiple tokens.
-### Adding phrase patterns {#adding-phrase-patterns}
+### Adding phrase patterns {id="adding-phrase-patterns"}
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy.matcher import PhraseMatcher
@@ -921,7 +960,7 @@ as a stream.
-### Matching on other token attributes {#phrasematcher-attrs new="2.1"}
+### Matching on other token attributes {id="phrasematcher-attrs",version="2.1"}
By default, the `PhraseMatcher` will match on the verbatim token text, e.g.
`Token.text`. By setting the `attr` argument on initialization, you can change
@@ -929,8 +968,7 @@ By default, the `PhraseMatcher` will match on the verbatim token text, e.g.
pattern to the matched `Doc`. For example, using the attribute `LOWER` lets you
match on `Token.lower` and create case-insensitive match patterns:
-```python
-### {executable="true"}
+```python {executable="true"}
from spacy.lang.en import English
from spacy.matcher import PhraseMatcher
@@ -948,7 +986,7 @@ for match_id, start, end in matcher(doc):
The examples here use [`nlp.make_doc`](/api/language#make_doc) to create `Doc`
object patterns as efficiently as possible and without running any of the other
-pipeline components. If the token attribute you want to match on are set by a
+pipeline components. If the token attribute you want to match on is set by a
pipeline component, **make sure that the pipeline component runs** when you
create the pattern. For example, to match on `POS` or `LEMMA`, the pattern `Doc`
objects need to have part-of-speech tags set by the `tagger` or `morphologizer`.
@@ -959,13 +997,12 @@ disable components selectively.
Another possible use case is matching number tokens like IP addresses based on
-their shape. This means that you won't have to worry about how those string will
-be tokenized and you'll be able to find tokens and combinations of tokens based
-on a few examples. Here, we're matching on the shapes `ddd.d.d.d` and
+their shape. This means that you won't have to worry about how those strings
+will be tokenized and you'll be able to find tokens and combinations of tokens
+based on a few examples. Here, we're matching on the shapes `ddd.d.d.d` and
`ddd.ddd.d.d`:
-```python
-### {executable="true"}
+```python {executable="true"}
from spacy.lang.en import English
from spacy.matcher import PhraseMatcher
@@ -985,7 +1022,7 @@ to match phrases with the same sequence of punctuation and non-punctuation
tokens as the pattern. But this can easily get confusing and doesn't have much
of an advantage over writing one or two token patterns.
-## Dependency Matcher {#dependencymatcher new="3" model="parser"}
+## Dependency Matcher {id="dependencymatcher",version="3",model="parser"}
The [`DependencyMatcher`](/api/dependencymatcher) lets you match patterns within
the dependency parse using
@@ -1053,7 +1090,7 @@ can be used as `LEFT_ID` in another dict.
-### Dependency matcher operators {#dependencymatcher-operators}
+### Dependency matcher operators {id="dependencymatcher-operators"}
The following operators are supported by the `DependencyMatcher`, most of which
come directly from
@@ -1074,7 +1111,7 @@ come directly from
| `A $++ B` | `B` is a right sibling of `A`, i.e. `A` and `B` have the same parent and `A.i < B.i`. |
| `A $-- B` | `B` is a left sibling of `A`, i.e. `A` and `B` have the same parent and `A.i > B.i`. |
-### Designing dependency matcher patterns {#dependencymatcher-patterns}
+### Designing dependency matcher patterns {id="dependencymatcher-patterns"}
Let's say we want to find sentences describing who founded what kind of company:
@@ -1099,9 +1136,11 @@ relations and tokens we want to match:
> displacy.serve(doc)
> ```
-import DisplaCyDepFoundedHtml from 'images/displacy-dep-founded.html'
-
-
+
The relations we're interested in are:
@@ -1119,8 +1158,7 @@ head to an immediate dependent as `head > child`.
The simplest dependency matcher pattern will identify and name a single token in
the tree:
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy.matcher import DependencyMatcher
@@ -1141,8 +1179,7 @@ print(matches) # [(4851363122962674176, [1])]
Now that we have a named anchor token (`anchor_founded`), we can add the founder
as the immediate dependent (`>`) of `founded` with the dependency label `nsubj`:
-```python
-### Step 1 {highlight="8,10"}
+```python {title="Step 1",highlight="8,10"}
pattern = [
{
"RIGHT_ID": "anchor_founded",
@@ -1160,8 +1197,7 @@ pattern = [
The direct object (`dobj`) is added in the same way:
-```python
-### Step 2 {highlight=""}
+```python {title="Step 2"}
pattern = [
#...
{
@@ -1181,8 +1217,7 @@ tokens into the pattern**. For the final part of our pattern, we'll specify that
the token `founded_object` should have a modifier with the dependency relation
`amod` or `compound`:
-```python
-### Step 3 {highlight="7"}
+```python {title="Step 3",highlight="7"}
pattern = [
# ...
{
@@ -1201,12 +1236,11 @@ each new token needs to be linked to an existing token on its left. As for
`founded` in this example, a token may be linked to more than one token on its
right:
-
+
The full pattern comes together as shown in the example below:
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy.matcher import DependencyMatcher
@@ -1262,14 +1296,14 @@ of patterns such as `{}` that match any token in the sentence.
-## Rule-based entity recognition {#entityruler new="2.1"}
+## Rule-based entity recognition {id="entityruler",version="2.1"}
The [`EntityRuler`](/api/entityruler) is a component that lets you add named
entities based on pattern dictionaries, which makes it easy to combine
rule-based and statistical named entity recognition for even more powerful
pipelines.
-### Entity Patterns {#entityruler-patterns}
+### Entity Patterns {id="entityruler-patterns"}
Entity patterns are dictionaries with two keys: `"label"`, specifying the label
to assign to the entity if the pattern is matched, and `"pattern"`, the match
@@ -1287,7 +1321,7 @@ pattern. The entity ruler accepts two types of patterns:
{"label": "GPE", "pattern": [{"LOWER": "san"}, {"LOWER": "francisco"}]}
```
-### Using the entity ruler {#entityruler-usage}
+### Using the entity ruler {id="entityruler-usage"}
The [`EntityRuler`](/api/entityruler) is a pipeline component that's typically
added via [`nlp.add_pipe`](/api/language#add_pipe). When the `nlp` object is
@@ -1297,8 +1331,7 @@ matches were to overlap, the pattern matching most tokens takes priority. If
they also happen to be equally long, then the match occurring first in the `Doc`
is chosen.
-```python
-### {executable="true"}
+```python {executable="true"}
from spacy.lang.en import English
nlp = English()
@@ -1320,8 +1353,7 @@ entity ruler will only add spans to the `doc.ents` if they don't overlap with
existing entities predicted by the model. To overwrite overlapping entities, you
can set `overwrite_ents=True` on initialization.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.load("en_core_web_sm")
@@ -1333,7 +1365,7 @@ doc = nlp("MyCorp Inc. is a company in the U.S.")
print([(ent.text, ent.label_) for ent in doc.ents])
```
-#### Validating and debugging EntityRuler patterns {#entityruler-pattern-validation new="2.1.8"}
+#### Validating and debugging EntityRuler patterns {id="entityruler-pattern-validation",version="2.1.8"}
The entity ruler can validate patterns against a JSON schema with the config
setting `"validate"`. See details under
@@ -1343,14 +1375,13 @@ setting `"validate"`. See details under
ruler = nlp.add_pipe("entity_ruler", config={"validate": True})
```
-### Adding IDs to patterns {#entityruler-ent-ids new="2.2.2"}
+### Adding IDs to patterns {id="entityruler-ent-ids",version="2.2.2"}
The [`EntityRuler`](/api/entityruler) can also accept an `id` attribute for each
pattern. Using the `id` attribute allows multiple patterns to be associated with
the same entity.
-```python
-### {executable="true"}
+```python {executable="true"}
from spacy.lang.en import English
nlp = English()
@@ -1372,15 +1403,14 @@ patterns, the `ent_id_` property of the matched entity is set to the `id` given
in the patterns. So in the example above it's easy to identify that "San
Francisco" and "San Fran" are both the same entity.
-### Using pattern files {#entityruler-files}
+### Using pattern files {id="entityruler-files"}
The [`to_disk`](/api/entityruler#to_disk) and
[`from_disk`](/api/entityruler#from_disk) let you save and load patterns to and
from JSONL (newline-delimited JSON) files, containing one pattern object per
line.
-```json
-### patterns.jsonl
+```json {title="patterns.jsonl"}
{"label": "ORG", "pattern": "Apple"}
{"label": "GPE", "pattern": [{"LOWER": "san"}, {"LOWER": "francisco"}]}
```
@@ -1417,9 +1447,9 @@ all pipeline components will be restored and deserialized – including the enti
ruler. This lets you ship powerful pipeline packages with binary weights _and_
rules included!
-### Using a large number of phrase patterns {#entityruler-large-phrase-patterns new="2.2.4"}
+### Using a large number of phrase patterns {id="entityruler-large-phrase-patterns",version="2.2.4"}
-
+{/* TODO: double-check that this still works if the ruler is added to the pipeline on creation, and include suggestion if needed */}
When using a large amount of **phrase patterns** (roughly > 10000) it's useful
to understand how the `add_patterns` function of the entity ruler works. For
@@ -1432,7 +1462,7 @@ of `"phrase_matcher_attr": "POS"` for the entity ruler.
Running the full language pipeline across every pattern in a large list scales
linearly and can therefore take a long time on large amounts of phrase patterns.
As of spaCy v2.2.4 the `add_patterns` function has been refactored to use
-nlp.pipe on all phrase patterns resulting in about a 10x-20x speed up with
+`nlp.pipe` on all phrase patterns resulting in about a 10x-20x speed up with
5,000-100,000 phrase patterns respectively. Even with this speedup (but
especially if you're using an older version) the `add_patterns` function can
still take a long time. An easy workaround to make this function run faster is
@@ -1445,7 +1475,106 @@ with nlp.select_pipes(enable="tagger"):
ruler.add_patterns(patterns)
```
-## Combining models and rules {#models-rules}
+## Rule-based span matching {id="spanruler",version="3.3.1"}
+
+The [`SpanRuler`](/api/spanruler) is a generalized version of the entity ruler
+that lets you add spans to `doc.spans` or `doc.ents` based on pattern
+dictionaries, which makes it easy to combine rule-based and statistical pipeline
+components.
+
+### Span patterns {id="spanruler-patterns"}
+
+The [pattern format](#entityruler-patterns) is the same as for the entity ruler:
+
+1. **Phrase patterns** for exact string matches (string).
+
+ ```python
+ {"label": "ORG", "pattern": "Apple"}
+ ```
+
+2. **Token patterns** with one dictionary describing one token (list).
+
+ ```python
+ {"label": "GPE", "pattern": [{"LOWER": "san"}, {"LOWER": "francisco"}]}
+ ```
+
+### Using the span ruler {id="spanruler-usage"}
+
+The [`SpanRuler`](/api/spanruler) is a pipeline component that's typically added
+via [`nlp.add_pipe`](/api/language#add_pipe). When the `nlp` object is called on
+a text, it will find matches in the `doc` and add them as spans to
+`doc.spans["ruler"]`, using the specified pattern label as the entity label.
+Unlike in `doc.ents`, overlapping matches are allowed in `doc.spans`, so no
+filtering is required, but optional filtering and sorting can be applied to the
+spans before they're saved.
+
+```python {executable="true"}
+import spacy
+
+nlp = spacy.blank("en")
+ruler = nlp.add_pipe("span_ruler")
+patterns = [{"label": "ORG", "pattern": "Apple"},
+ {"label": "GPE", "pattern": [{"LOWER": "san"}, {"LOWER": "francisco"}]}]
+ruler.add_patterns(patterns)
+
+doc = nlp("Apple is opening its first big office in San Francisco.")
+print([(span.text, span.label_) for span in doc.spans["ruler"]])
+```
+
+The span ruler is designed to integrate with spaCy's existing pipeline
+components and enhance the [SpanCategorizer](/api/spancat) and
+[EntityRecognizer](/api/entityrecognizer). The `overwrite` setting determines
+whether the existing annotation in `doc.spans` or `doc.ents` is preserved.
+Because overlapping entities are not allowed for `doc.ents`, the entities are
+always filtered, using [`util.filter_spans`](/api/top-level#util.filter_spans)
+by default. See the [`SpanRuler` API docs](/api/spanruler) for more information
+about how to customize the sorting and filtering of matched spans.
+
+```python {executable="true"}
+import spacy
+
+nlp = spacy.load("en_core_web_sm")
+# only annotate doc.ents, not doc.spans
+config = {"spans_key": None, "annotate_ents": True, "overwrite": False}
+ruler = nlp.add_pipe("span_ruler", config=config)
+patterns = [{"label": "ORG", "pattern": "MyCorp Inc."}]
+ruler.add_patterns(patterns)
+
+doc = nlp("MyCorp Inc. is a company in the U.S.")
+print([(ent.text, ent.label_) for ent in doc.ents])
+```
+
+### Using pattern files {id="spanruler-files"}
+
+You can save patterns in a JSONL file (newline-delimited JSON) to load with
+[`SpanRuler.initialize`](/api/spanruler#initialize) or
+[`SpanRuler.add_patterns`](/api/spanruler#add_patterns).
+
+```json {title="patterns.jsonl"}
+{"label": "ORG", "pattern": "Apple"}
+{"label": "GPE", "pattern": [{"LOWER": "san"}, {"LOWER": "francisco"}]}
+```
+
+```python
+import srsly
+
+patterns = srsly.read_jsonl("patterns.jsonl")
+ruler = nlp.add_pipe("span_ruler")
+ruler.add_patterns(patterns)
+```
+
+
+
+Unlike the entity ruler, the span ruler cannot load patterns on initialization
+with `SpanRuler(patterns=patterns)` or directly from a JSONL file path with
+`SpanRuler.from_disk(jsonl_path)`. Patterns should be loaded from the JSONL file
+separately and then added through
+[`SpanRuler.initialize`](/api/spanruler#initialize]) or
+[`SpanRuler.add_patterns`](/api/spanruler#add_patterns) as shown above.
+
+
+
+## Combining models and rules {id="models-rules"}
You can combine statistical and rule-based components in a variety of ways.
Rule-based components can be used to improve the accuracy of statistical models,
@@ -1456,7 +1585,7 @@ components after a statistical model to correct common errors. Finally,
rule-based components can reference the attributes set by statistical models, in
order to implement more abstract logic.
-### Example: Expanding named entities {#models-rules-ner}
+### Example: Expanding named entities {id="models-rules-ner"}
When using a trained
[named entity recognition](/usage/linguistic-features/#named-entities) model to
@@ -1482,8 +1611,7 @@ or "Dr.". This makes sense, because it makes it easier to resolve the entity
type back to a knowledge base. But what if your application needs the full
names, _including_ the titles?
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.load("en_core_web_sm")
@@ -1502,8 +1630,7 @@ expands the entity span by one token. After all, what all titles in this example
have in common is that _if_ they occur, they occur in the **previous token**
right before the person entity.
-```python
-### {highlight="9-13"}
+```python {highlight="9-13"}
from spacy.language import Language
from spacy.tokens import Span
@@ -1531,8 +1658,7 @@ register it as a [pipeline component](/usage/processing-pipelines) so it can run
automatically when processing a text. We can use
[`nlp.add_pipe`](/api/language#add_pipe) to add it to the current pipeline.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy.language import Language
from spacy.tokens import Span
@@ -1581,8 +1707,7 @@ We can now use the [`Span.set_extension`](/api/span#set_extension) method to add
the custom extension attribute `"person_title"`, using `get_person_title` as the
getter function.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy.tokens import Span
@@ -1601,7 +1726,7 @@ doc = nlp("Dr Alex Smith chaired first board meeting of Acme Corp Inc.")
print([(ent.text, ent.label_, ent._.person_title) for ent in doc.ents])
```
-### Example: Using entities, part-of-speech tags and the dependency parse {#models-rules-pos-dep}
+### Example: Using entities, part-of-speech tags and the dependency parse {id="models-rules-pos-dep"}
> #### Linguistic features
>
@@ -1624,8 +1749,7 @@ tense**, whether company names are attached to it and whether the person is the
subject. All of this information is available in the part-of-speech tags and the
dependency parse.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.load("en_core_web_sm")
@@ -1640,7 +1764,7 @@ print([(ent.text, ent.label_) for ent in doc.ents])
> - `VBD`: Verb, past tense.
> - `IN`: Conjunction, subordinating or preposition.
- visualization with `options={'fine_grained': True}` to output the fine-grained part-of-speech tags, i.e. `Token.tag_`")
+ visualization with `options={'fine_grained': True}` to output the fine-grained part-of-speech tags, i.e. `Token.tag_`")
In this example, "worked" is the root of the sentence and is a past tense verb.
Its subject is "Alex Smith", the person who worked. "at Acme Corp Inc." is a
@@ -1684,13 +1808,12 @@ the entity `Span` – for example `._.orgs` or `._.prev_orgs` and
> [`Doc.retokenize`](/api/doc#retokenize) context manager:
>
> ```python
-> with doc.retokenize() as retokenize:
+> with doc.retokenize() as retokenizer:
> for ent in doc.ents:
> retokenizer.merge(ent)
> ```
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy.language import Language
from spacy import displacy
@@ -1723,12 +1846,11 @@ notice that our current logic fails and doesn't correctly detect the company as
a past organization. That's because the root is a participle and the tense
information is in the attached auxiliary "was":
-
+
To solve this, we can adjust the rules to also check for the above construction:
-```python
-### {highlight="10-12"}
+```python {highlight="10-12"}
@Language.component("extract_person_orgs")
def extract_person_orgs(doc):
person_entities = [ent for ent in doc.ents if ent.label_ == "PERSON"]
diff --git a/website/docs/usage/saving-loading.md b/website/docs/usage/saving-loading.mdx
similarity index 87%
rename from website/docs/usage/saving-loading.md
rename to website/docs/usage/saving-loading.mdx
index 9dad077e7..e0daebe35 100644
--- a/website/docs/usage/saving-loading.md
+++ b/website/docs/usage/saving-loading.mdx
@@ -8,13 +8,11 @@ menu:
- ['Trained Pipelines', 'models']
---
-## Basics {#basics hidden="true"}
-
-import Serialization101 from 'usage/101/\_serialization.md'
+## Basics {id="basics",hidden="true"}
-### Serializing the pipeline {#pipeline}
+### Serializing the pipeline {id="pipeline"}
When serializing the pipeline, keep in mind that this will only save out the
**binary data for the individual components** to allow spaCy to restore them –
@@ -30,14 +28,12 @@ contains the pipeline configuration and all the relevant settings.
> dictionary containing the training configuration, pipeline component factories
> and other settings. It is saved out with a pipeline as the `config.cfg`.
-```python
-### Serialize
+```python {title="Serialize"}
config = nlp.config
bytes_data = nlp.to_bytes()
```
-```python
-### Deserialize
+```python {title="Deserialize"}
lang_cls = spacy.util.get_lang_class(config["nlp"]["lang"])
nlp = lang_cls.from_config(config)
nlp.from_bytes(bytes_data)
@@ -49,7 +45,7 @@ the language class, creates and adds the pipeline components based on the config
and _then_ loads in the binary data. You can read more about this process
[here](/usage/processing-pipelines#pipelines).
-## Serializing Doc objects efficiently {#docs new="2.2"}
+## Serializing Doc objects efficiently {id="docs",version="2.2"}
If you're working with lots of data, you'll probably need to pass analyses
between machines, either to use something like [Dask](https://dask.org) or
@@ -64,8 +60,7 @@ collection of `Doc` objects together, and is much more efficient than calling
also control what data gets saved, and you can merge pallets together for easy
map/reduce-style processing.
-```python
-### {highlight="4,8,9,13,14"}
+```python {highlight="4,8,9,13,14"}
import spacy
from spacy.tokens import DocBin
@@ -101,7 +96,7 @@ print([doc._.my_custom_attr for doc in docs])
-### Using Pickle {#pickle}
+### Using Pickle {id="pickle"}
> #### Example
>
@@ -124,8 +119,7 @@ the entire pipeline once. And instead of pickling several `Doc` objects
separately, pickle a list of `Doc` objects. Since they all share a reference to
the _same_ `Vocab` object, it will only be included once.
-```python
-### Pickling objects with shared data {highlight="8-9"}
+```python {title="Pickling objects with shared data",highlight="8-9"}
doc1 = nlp("Hello world")
doc2 = nlp("This is a test")
@@ -161,7 +155,7 @@ data = pickle.dumps(span_doc)
-## Implementing serialization methods {#serialization-methods}
+## Implementing serialization methods {id="serialization-methods"}
When you call [`nlp.to_disk`](/api/language#to_disk),
[`nlp.from_disk`](/api/language#from_disk) or load a pipeline package, spaCy
@@ -201,11 +195,15 @@ the data to and from a JSON file.
> saving out a pipeline with a rule-based entity recognizer and including all
> rules _with_ the component data.
-```python
-### {highlight="14-18,20-25"}
+```python {highlight="16-23,25-30"}
+import json
+from spacy import Language
+from spacy.util import ensure_path
+
@Language.factory("my_component")
class CustomComponent:
- def __init__(self):
+ def __init__(self, nlp: Language, name: str = "my_component"):
+ self.name = name
self.data = []
def __call__(self, doc):
@@ -218,6 +216,9 @@ class CustomComponent:
def to_disk(self, path, exclude=tuple()):
# This will receive the directory path + /my_component
+ path = ensure_path(path)
+ if not path.exists():
+ path.mkdir()
data_path = path / "data.json"
with data_path.open("w", encoding="utf8") as f:
f.write(json.dumps(self.data))
@@ -226,7 +227,7 @@ class CustomComponent:
# This will receive the directory path + /my_component
data_path = path / "data.json"
with data_path.open("r", encoding="utf8") as f:
- self.data = json.loads(f)
+ self.data = json.load(f)
return self
```
@@ -234,8 +235,7 @@ After adding the component to the pipeline and adding some data to it, we can
serialize the `nlp` object to a directory, which will call the custom
component's `to_disk` method.
-```python
-### {highlight="2-4"}
+```python {highlight="2-4"}
nlp = spacy.load("en_core_web_sm")
my_component = nlp.add_pipe("my_component")
my_component.add({"hello": "world"})
@@ -246,8 +246,7 @@ The contents of the directory would then look like this.
`CustomComponent.to_disk` converted the data to a JSON string and saved it to a
file `data.json` in its subdirectory:
-```yaml
-### Directory structure {highlight="2-3"}
+```yaml {title="Directory structure",highlight="2-3"}
└── /path/to/pipeline
├── my_component # data serialized by "my_component"
│ └── data.json
@@ -284,9 +283,9 @@ custom components to spaCy automatically.
-
+{/* ## Initializing components with data {id="initialization",version="3"} */}
-## Using entry points {#entry-points new="2.1"}
+## Using entry points {id="entry-points",version="2.1"}
Entry points let you expose parts of a Python package you write to other Python
packages. This lets one application easily customize the behavior of another, by
@@ -298,14 +297,14 @@ pipeline component factories, language classes and other settings. To make spaCy
use your entry points, your package needs to expose them and it needs to be
installed in the same environment – that's it.
-| Entry point | Description |
-| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`spacy_factories`](#entry-points-components) | Group of entry points for pipeline component factories, keyed by component name. Can be used to expose custom components defined by another package. |
-| [`spacy_languages`](#entry-points-languages) | Group of entry points for custom [`Language` subclasses](/usage/linguistic-features#language-data), keyed by language shortcut. |
-| `spacy_lookups` 2.2 | Group of entry points for custom [`Lookups`](/api/lookups), including lemmatizer data. Used by spaCy's [`spacy-lookups-data`](https://github.com/explosion/spacy-lookups-data) package. |
-| [`spacy_displacy_colors`](#entry-points-displacy) 2.2 | Group of entry points of custom label colors for the [displaCy visualizer](/usage/visualizers#ent). The key name doesn't matter, but it should point to a dict of labels and color values. Useful for custom models that predict different entity types. |
+| Entry point | Description |
+| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`spacy_factories`](#entry-points-components) | Group of entry points for pipeline component factories, keyed by component name. Can be used to expose custom components defined by another package. |
+| [`spacy_languages`](#entry-points-languages) | Group of entry points for custom [`Language` subclasses](/usage/linguistic-features#language-data), keyed by language shortcut. |
+| `spacy_lookups` | Group of entry points for custom [`Lookups`](/api/lookups), including lemmatizer data. Used by spaCy's [`spacy-lookups-data`](https://github.com/explosion/spacy-lookups-data) package. |
+| [`spacy_displacy_colors`](#entry-points-displacy) | Group of entry points of custom label colors for the [displaCy visualizer](/usage/visualizers#ent). The key name doesn't matter, but it should point to a dict of labels and color values. Useful for custom models that predict different entity types. |
-### Custom components via entry points {#entry-points-components}
+### Custom components via entry points {id="entry-points-components"}
When you load a pipeline, spaCy will generally use its `config.cfg` to set up
the language class and construct the pipeline. The pipeline is specified as a
@@ -335,8 +334,7 @@ snake when it's called:
> └── setup.py # setup file for pip installation
> ```
-```python
-### snek.py
+```python {title="snek.py"}
from spacy.language import Language
snek = """
@@ -369,8 +367,7 @@ entry to the factories, you can now expose it in your `setup.py` via the
> the created entry point is named `snek` and points to the function
> `snek_component` in the module `snek`, i.e. `snek.py`.
-```python
-### setup.py {highlight="5-7"}
+```python {title="setup.py",highlight="5-7"}
from setuptools import setup
setup(
@@ -451,8 +448,7 @@ class SnekFactory:
return doc
```
-```diff
-### setup.py
+```diff {title="setup.py"}
entry_points={
- "spacy_factories": ["snek = snek:snek_component"]
+ "spacy_factories": ["snek = snek:SnekFactory"]
@@ -467,7 +463,12 @@ pipeline package. When you save out a pipeline using `nlp.to_disk` and the
component exposes a `to_disk` method, it will be called with the disk path.
```python
+from spacy.util import ensure_path
+
def to_disk(self, path, exclude=tuple()):
+ path = ensure_path(path)
+ if not path.exists():
+ path.mkdir()
snek_path = path / "snek.txt"
with snek_path.open("w", encoding="utf8") as snek_file:
snek_file.write(self.snek)
@@ -483,7 +484,7 @@ The above example will serialize the current snake in a `snek.txt` in the data
directory. When a pipeline using the `snek` component is loaded, it will open
the `snek.txt` and make it available to the component.
-### Custom language classes via entry points {#entry-points-languages}
+### Custom language classes via entry points {id="entry-points-languages"}
To stay with the theme of the previous example and
[this blog post on entry points](https://amir.rachum.com/blog/2017/07/28/python-entry-points/),
@@ -492,8 +493,7 @@ custom pipeline – but you don't necessarily want to modify spaCy's code to ad
language. In your package, you could then implement the following
[custom language subclass](/usage/linguistic-features#language-subclass):
-```python
-### snek.py
+```python {title="snek.py"}
from spacy.language import Language
class SnekDefaults(Language.Defaults):
@@ -508,8 +508,7 @@ Alongside the `spacy_factories`, there's also an entry point option for
`spacy_languages`, which maps language codes to language-specific `Language`
subclasses:
-```diff
-### setup.py
+```diff {title="setup.py"}
from setuptools import setup
setup(
@@ -527,7 +526,7 @@ pipeline packages you [train](/usage/training), which could then specify
`lang = snk` in their `config.cfg` without spaCy raising an error because the
language is not available in the core library.
-### Custom displaCy colors via entry points {#entry-points-displacy new="2.2"}
+### Custom displaCy colors via entry points {id="entry-points-displacy",version="2.2"}
If you're training a named entity recognition model for a custom domain, you may
end up training different labels that don't have pre-defined colors in the
@@ -542,8 +541,7 @@ values.
> [scispaCy](/universe/project/scispacy) and
> [Blackstone](/universe/project/blackstone).
-```python
-### snek.py
+```python {title="snek.py"}
displacy_colors = {"SNEK": "#3dff74", "HUMAN": "#cfc5ff"}
```
@@ -551,8 +549,7 @@ Given the above colors, the entry point can be defined as follows. Entry points
need to have a name, so we use the key `colors`. However, the name doesn't
matter and whatever is defined in the entry point group will be used.
-```diff
-### setup.py
+```diff {title="setup.py"}
from setuptools import setup
setup(
@@ -567,11 +564,13 @@ After installing the package, the custom colors will be used when visualizing
text with `displacy`. Whenever the label `SNEK` is assigned, it will be
displayed in `#3dff74`.
-import DisplaCyEntSnekHtml from 'images/displacy-ent-snek.html'
+
-
-
-## Saving, loading and distributing trained pipelines {#models}
+## Saving, loading and distributing trained pipelines {id="models"}
After training your pipeline, you'll usually want to save its state, and load it
back later. You can do this with the [`Language.to_disk`](/api/language#to_disk)
@@ -616,7 +615,7 @@ Universal Dependencies treebank and generates an installable Python package.
-### Generating a pipeline package {#models-generating}
+### Generating a pipeline package {id="models-generating"}
@@ -649,7 +648,7 @@ this, see the [`package`](/api/cli#package) docs.
> }
> ```
-```cli
+```bash
$ python -m spacy package ./en_example_pipeline ./packages
```
@@ -658,8 +657,7 @@ This command will create a pipeline package directory and will run
`.tar.gz` archive of your package that can be installed using `pip install`.
Installing the binary wheel is usually more efficient.
-```yaml
-### Directory structure
+```yaml {title="Directory structure"}
└── /
├── MANIFEST.in # to include meta.json
├── meta.json # pipeline meta data
@@ -680,16 +678,21 @@ If you're creating the package manually, keep in mind that the directories need
to be named according to the naming conventions of `lang_name` and
`lang_name-version`.
-### Including custom functions and components {#models-custom}
+### Including custom functions and components {id="models-custom"}
If your pipeline includes
[custom components](/usage/processing-pipelines#custom-components), model
architectures or other [code](/usage/training#custom-code), those functions need
to be registered **before** your pipeline is loaded. Otherwise, spaCy won't know
-how to create the objects referenced in the config. The
-[`spacy package`](/api/cli#package) command lets you provide one or more paths
-to Python files containing custom registered functions using the `--code`
-argument.
+how to create the objects referenced in the config. If you're loading your own
+pipeline in Python, you can make custom components available just by importing
+the code that defines them before calling
+[`spacy.load`](/api/top-level#spacy.load). This is also how the `--code`
+argument to CLI commands works.
+
+With the [`spacy package`](/api/cli#package) command, you can provide one or
+more paths to Python files containing custom registered functions using the
+`--code` argument.
> #### \_\_init\_\_.py (excerpt)
>
@@ -700,7 +703,7 @@ argument.
> ...
> ```
-```cli
+```bash
$ python -m spacy package ./en_example_pipeline ./packages --code functions.py
```
@@ -731,7 +734,7 @@ spaCy to export the current state of its `nlp` objects via
-### Loading a custom pipeline package {#loading}
+### Loading a custom pipeline package {id="loading"}
To load a pipeline from a data directory, you can use
[`spacy.load()`](/api/top-level#spacy.load) with the local path. This will look
diff --git a/website/docs/usage/spacy-101.md b/website/docs/usage/spacy-101.mdx
similarity index 91%
rename from website/docs/usage/spacy-101.md
rename to website/docs/usage/spacy-101.mdx
index 52daf33b8..a02e73508 100644
--- a/website/docs/usage/spacy-101.md
+++ b/website/docs/usage/spacy-101.mdx
@@ -30,18 +30,24 @@ quick introduction.
-[](https://course.spacy.io)
+
In this course you'll learn how to use spaCy to build advanced natural language
understanding systems, using both rule-based and machine learning approaches. It
includes 55 exercises featuring interactive coding practice, multiple-choice
questions and slide decks.
-
+
-## What's spaCy? {#whats-spacy}
+## What's spaCy? {id="whats-spacy"}
@@ -82,7 +88,7 @@ systems, or to pre-process text for **deep learning**.
-### What spaCy isn't {#what-spacy-isnt}
+### What spaCy isn't {id="what-spacy-isnt"}
- ❌ **spaCy is not a platform or "an API"**. Unlike a platform, spaCy does not
provide a software as a service, or a web application. It's an open-source
@@ -103,7 +109,7 @@ systems, or to pre-process text for **deep learning**.
publishing spaCy and other software is called
[Explosion](https://explosion.ai).
-## Features {#features}
+## Features {id="features"}
In the documentation, you'll come across mentions of spaCy's features and
capabilities. Some of them refer to linguistic concepts, while others are
@@ -124,7 +130,7 @@ related to more general machine learning functionality.
| **Training** | Updating and improving a statistical model's predictions. |
| **Serialization** | Saving objects to files or byte strings. |
-### Statistical models {#statistical-models}
+### Statistical models {id="statistical-models"}
While some of spaCy's features work independently, others require
[trained pipelines](/models) to be loaded, which enable spaCy to **predict**
@@ -148,7 +154,7 @@ are always a good start. They typically include the following components:
and model implementations to use, to put spaCy in the correct state when you
load the pipeline.
-## Linguistic annotations {#annotations}
+## Linguistic annotations {id="annotations"}
spaCy provides a variety of linguistic annotations to give you **insights into a
text's grammatical structure**. This includes the word types, like the parts of
@@ -159,7 +165,7 @@ the website or company in a specific context.
> #### Loading pipelines
>
-> ```cli
+> ```bash
> $ python -m spacy download en_core_web_sm
>
> >>> import spacy
@@ -172,8 +178,7 @@ can load it via [`spacy.load`](/api/top-level#spacy.load). This will return a
usually call it `nlp`. Calling the `nlp` object on a string of text will return
a processed `Doc`:
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.load("en_core_web_sm")
@@ -189,9 +194,7 @@ original string, or reconstruct the original by joining the tokens and their
trailing whitespace. This way, you'll never lose any information when processing
text with spaCy.
-### Tokenization {#annotations-token}
-
-import Tokenization101 from 'usage/101/\_tokenization.md'
+### Tokenization {id="annotations-token"}
@@ -205,9 +208,7 @@ language-specific data**, see the usage guides on
-### Part-of-speech tags and dependencies {#annotations-pos-deps model="parser"}
-
-import PosDeps101 from 'usage/101/\_pos-deps.md'
+### Part-of-speech tags and dependencies {id="annotations-pos-deps",model="parser"}
@@ -220,9 +221,7 @@ how to **navigate and use the parse tree** effectively, see the usage guides on
-### Named Entities {#annotations-ner model="ner"}
-
-import NER101 from 'usage/101/\_named-entities.md'
+### Named Entities {id="annotations-ner",model="ner"}
@@ -236,9 +235,7 @@ of a model, see the usage guides on
-### Word vectors and similarity {#vectors-similarity model="vectors"}
-
-import Vectors101 from 'usage/101/\_vectors-similarity.md'
+### Word vectors and similarity {id="vectors-similarity",model="vectors"}
@@ -250,9 +247,7 @@ To learn more about word vectors, how to **customize them** and how to load
-## Pipelines {#pipelines}
-
-import Pipelines101 from 'usage/101/\_pipelines.md'
+## Pipelines {id="pipelines"}
@@ -264,13 +259,11 @@ guide on [language processing pipelines](/usage/processing-pipelines).
-## Architecture {#architecture}
-
-import Architecture101 from 'usage/101/\_architecture.md'
+## Architecture {id="architecture"}
-## Vocab, hashes and lexemes {#vocab}
+## Vocab, hashes and lexemes {id="vocab"}
Whenever possible, spaCy tries to store data in a vocabulary, the
[`Vocab`](/api/vocab), that will be **shared by multiple documents**. To save
@@ -288,7 +281,7 @@ and part-of-speech tags like "VERB" are also encoded. Internally, spaCy only
> - **StringStore**: The dictionary mapping hash values to strings, for example
> `3197928453018144401` → "coffee".
-
+
If you process lots of documents containing the word "coffee" in all kinds of
different contexts, storing the exact string "coffee" every time would take up
@@ -297,8 +290,7 @@ way too much space. So instead, spaCy hashes the string and stores it in the
**lookup table that works in both directions** – you can look up a string to get
its hash, or a hash to get its string:
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.load("en_core_web_sm")
@@ -315,8 +307,7 @@ a word. For example, no matter if "love" is used as a verb or a noun in some
context, its spelling and whether it consists of alphabetic characters won't
ever change. Its hash value will also always be the same.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
nlp = spacy.load("en_core_web_sm")
@@ -354,8 +345,7 @@ vocabulary. That's why you always need to make sure all objects you create have
access to the same vocabulary. If they don't, spaCy might not be able to find
the strings it needs.
-```python
-### {executable="true"}
+```python {executable="true"}
import spacy
from spacy.tokens import Doc
from spacy.vocab import Vocab
@@ -382,9 +372,7 @@ spaCy will also export the `Vocab` when you save a `Doc` or `nlp` object. This
will give you the object and its encoded annotations, plus the "key" to decode
it.
-## Serialization {#serialization}
-
-import Serialization101 from 'usage/101/\_serialization.md'
+## Serialization {id="serialization"}
@@ -395,9 +383,7 @@ guide on [saving and loading](/usage/saving-loading#models).
-## Training {#training}
-
-import Training101 from 'usage/101/\_training.md'
+## Training {id="training"}
@@ -409,7 +395,7 @@ data and how to improve spaCy's named models, see the usage guides on
-### Training config and lifecycle {#training-config}
+### Training config and lifecycle {id="training-config"}
Training config files include all **settings and hyperparameters** for training
your pipeline. Instead of providing lots of arguments on the command line, you
@@ -433,7 +419,7 @@ source of truth", both at **training** and **runtime**.
> initial_rate = 0.01
> ```
-
+
@@ -443,7 +429,7 @@ hyperparameters, see the [training config](/usage/training#config) usage guide.
-### Trainable components {#training-components}
+### Trainable components {id="training-components"}
spaCy's [`Pipe`](/api/pipe) class helps you implement your own trainable
components that have their own model instance, make predictions over `Doc`
@@ -462,7 +448,7 @@ configured via a single training config.
> width = 128
> ```
-
+
@@ -474,13 +460,11 @@ for trainable components.
-## Language data {#language-data}
-
-import LanguageData101 from 'usage/101/\_language-data.md'
+## Language data {id="language-data"}
-## Community & FAQ {#community-faq}
+## Community & FAQ {id="community-faq"}
We're very happy to see the spaCy community grow and include a mix of people
from all kinds of different backgrounds – computational linguistics, data
@@ -488,7 +472,7 @@ science, deep learning, research and more. If you'd like to get involved, below
are some answers to the most important questions and resources for further
reading.
-### Help, my code isn't working! {#faq-help-code}
+### Help, my code isn't working! {id="faq-help-code"}
Bugs suck, and we're doing our best to continuously improve the tests and fix
bugs as soon as possible. Before you submit an issue, do a quick search and
@@ -513,10 +497,11 @@ via the following platforms:
questions** and everything related to problems with your specific code. The
Stack Overflow community is much larger than ours, so if your problem can be
solved by others, you'll receive help much quicker.
-- [GitHub discussions](https://github.com/explosion/spaCy/discussions): **General
- discussion**, **project ideas** and **usage questions**. Meet other community
- members to get help with a specific code implementation, discuss ideas for new
- projects/plugins, support more languages, and share best practices.
+- [GitHub discussions](https://github.com/explosion/spaCy/discussions):
+ **General discussion**, **project ideas** and **usage questions**. Meet other
+ community members to get help with a specific code implementation, discuss
+ ideas for new projects/plugins, support more languages, and share best
+ practices.
- [GitHub issue tracker](https://github.com/explosion/spaCy/issues): **Bug
reports** and **improvement suggestions**, i.e. everything that's likely
spaCy's fault. This also includes problems with the trained pipelines beyond
@@ -533,7 +518,7 @@ and the next time you need help, they might repay the favor.
-### How can I contribute to spaCy? {#faq-contributing}
+### How can I contribute to spaCy? {id="faq-contributing"}
You don't have to be an NLP expert or Python pro to contribute, and we're happy
to help you get started. If you're new to spaCy, a good place to start is the
@@ -567,7 +552,7 @@ By participating, you are expected to uphold this code.
-### I've built something cool with spaCy – how can I get the word out? {#faq-project-with-spacy}
+### I've built something cool with spaCy – how can I get the word out? {id="faq-project-with-spacy"}
First, congrats – we'd love to check it out! When you share your project on
Twitter, don't forget to tag [@spacy_io](https://twitter.com/spacy_io) so we
@@ -588,7 +573,8 @@ project is using spaCy, you can grab one of our **spaCy badges** here:
[](https://spacy.io)
```
-
```markdown
diff --git a/website/docs/usage/training.md b/website/docs/usage/training.mdx
similarity index 95%
rename from website/docs/usage/training.md
rename to website/docs/usage/training.mdx
index f46f0052b..6cda975cb 100644
--- a/website/docs/usage/training.md
+++ b/website/docs/usage/training.mdx
@@ -15,15 +15,17 @@ menu:
- ['Internal API', 'api']
---
-## Introduction to training {#basics hidden="true"}
-
-import Training101 from 'usage/101/\_training.md'
+## Introduction to training {id="basics",hidden="true"}
-[](https://prodi.gy)
+
If you need to label a lot of data, check out [Prodigy](https://prodi.gy), a
new, active learning-powered annotation tool we've developed. Prodigy is fast
@@ -34,7 +36,7 @@ ready-to-use spaCy pipelines.
-## Quickstart {#quickstart tag="new"}
+## Quickstart {id="quickstart",tag="new"}
The recommended way to train your spaCy pipelines is via the
[`spacy train`](/api/cli#train) command on the command line. It only needs a
@@ -69,8 +71,6 @@ config.
> requirements and settings as CLI arguments.
> 2. Run [`train`](/api/cli#train) with the exported config and data.
-import QuickstartTraining from 'widgets/quickstart-training.js'
-
After you've saved the starter config to a file `base_config.cfg`, you can use
@@ -78,7 +78,7 @@ the [`init fill-config`](/api/cli#init-fill-config) command to fill in the
remaining defaults. Training configs should always be **complete and without
hidden defaults**, to keep your experiments reproducible.
-```cli
+```bash
$ python -m spacy init fill-config base_config.cfg config.cfg
```
@@ -88,7 +88,7 @@ $ python -m spacy init fill-config base_config.cfg config.cfg
> your training and development data, get useful stats, and find problems like
> invalid entity annotations, cyclic dependencies, low data labels and more.
>
-> ```cli
+> ```bash
> $ python -m spacy debug data config.cfg
> ```
@@ -100,7 +100,7 @@ add your data and run [`train`](/api/cli#train) with your config. See the
spaCy's binary `.spacy` format. You can either include the data paths in the
`[paths]` section of your config, or pass them in via the command line.
-```cli
+```bash
$ python -m spacy train config.cfg --output ./output --paths.train ./train.spacy --paths.dev ./dev.spacy
```
@@ -108,7 +108,7 @@ $ python -m spacy train config.cfg --output ./output --paths.train ./train.spacy
>
> Use the `--gpu-id` option to select the GPU:
>
-> ```cli
+> ```bash
> $ python -m spacy train config.cfg --gpu-id 0
> ```
@@ -141,7 +141,7 @@ treebank.
-## Training config system {#config}
+## Training config system {id="config"}
Training config files include all **settings and hyperparameters** for training
your pipeline. Instead of providing lots of arguments on the command line, you
@@ -212,7 +212,7 @@ available for the different architectures are documented with the
-### Config lifecycle at runtime and training {#config-lifecycle}
+### Config lifecycle at runtime and training {id="config-lifecycle"}
A pipeline's `config.cfg` is considered the "single source of truth", both at
**training** and **runtime**. Under the hood,
@@ -222,7 +222,7 @@ config is available as [`nlp.config`](/api/language#config) and it includes all
information about the pipeline, as well as the settings used to train and
initialize it.
-
+
At runtime spaCy will only use the `[nlp]` and `[components]` blocks of the
config and load all data, including tokenization rules, model weights and other
@@ -240,21 +240,21 @@ requiring it to be available at runtime. You can also use this mechanism to
provide data paths to custom pipeline components and custom tokenizers – see the
section on [custom initialization](#initialization) for details.
-### Overwriting config settings on the command line {#config-overrides}
+### Overwriting config settings on the command line {id="config-overrides"}
The config system means that you can define all settings **in one place** and in
a consistent format. There are no command-line arguments that need to be set,
and no hidden defaults. However, there can still be scenarios where you may want
to override config settings when you run [`spacy train`](/api/cli#train). This
includes **file paths** to vectors or other resources that shouldn't be
-hard-code in a config file, or **system-dependent settings**.
+hard-coded in a config file, or **system-dependent settings**.
For cases like this, you can set additional command-line options starting with
`--` that correspond to the config section and value to override. For example,
`--paths.train ./corpus/train.spacy` sets the `train` value in the `[paths]`
block.
-```cli
+```bash
$ python -m spacy train config.cfg --paths.train ./corpus/train.spacy --paths.dev ./corpus/dev.spacy --training.batch_size 128
```
@@ -271,7 +271,7 @@ reference it across your config and override it on the CLI once.
> [`spacy train`](/api/cli#train) to make spaCy log more info, including which
> overrides were set via the CLI and environment variables.
-#### Adding overrides via environment variables {#config-overrides-env}
+#### Adding overrides via environment variables {id="config-overrides-env"}
Instead of defining the overrides as CLI arguments, you can also use the
`SPACY_CONFIG_OVERRIDES` environment variable using the same argument syntax.
@@ -279,11 +279,11 @@ This is especially useful if you're training models as part of an automated
process. Environment variables **take precedence** over CLI overrides and values
defined in the config file.
-```cli
+```bash
$ SPACY_CONFIG_OVERRIDES="--system.gpu_allocator pytorch --training.batch_size 128" ./your_script.sh
```
-### Reading from standard input {#config-stdin}
+### Reading from standard input {id="config-stdin"}
Setting the config path to `-` on the command line lets you read the config from
standard input and pipe it forward from a different process, like
@@ -297,11 +297,11 @@ fly without having to save to and load from disk.
> stdout. In a custom script, you can print the string config, e.g.
> `print(nlp.config.to_str())`.
-```cli
+```bash
$ python -m spacy init config - --lang en --pipeline ner,textcat --optimize accuracy | python -m spacy train - --paths.train ./corpus/train.spacy --paths.dev ./corpus/dev.spacy
```
-### Using variable interpolation {#config-interpolation}
+### Using variable interpolation {id="config-interpolation"}
Another very useful feature of the config system is that it supports variable
interpolation for both **values and sections**. This means that you only need to
@@ -310,8 +310,7 @@ define a setting once and can reference it across your config using the
the `[training]` block, and the whole block of `[training.optimizer]` is reused
in `[pretraining]` and will become `pretraining.optimizer`.
-```ini
-### config.cfg (excerpt) {highlight="5,18"}
+```ini {title="config.cfg (excerpt)",highlight="5,18"}
[system]
seed = 0
@@ -354,7 +353,7 @@ that reference this variable.
-## Preparing Training Data {#training-data}
+## Preparing Training Data {id="training-data"}
Training data for NLP projects comes in many different formats. For some common
formats such as CoNLL, spaCy provides [converters](/api/cli#convert) you can use
@@ -372,8 +371,7 @@ are handled automatically.
Here's an example of creating a `.spacy` file from some NER annotations.
-```python
-### preprocess.py
+```python {title="preprocess.py"}
import spacy
from spacy.tokens import DocBin
@@ -407,9 +405,9 @@ convert your data to JSON before creating a `.spacy` file.
-## Customizing the pipeline and training {#config-custom}
+## Customizing the pipeline and training {id="config-custom"}
-### Defining pipeline components {#config-components}
+### Defining pipeline components {id="config-components"}
You typically train a [pipeline](/usage/processing-pipelines) of **one or more
components**. The `[components]` block in the config defines the available
@@ -438,8 +436,7 @@ existing weights. This lets you include an already trained component in your
pipeline, or update a trained component with more data specific to your use
case.
-```ini
-### config.cfg (excerpt)
+```ini {title="config.cfg (excerpt)"}
[components]
# "parser" and "ner" are sourced from a trained pipeline
@@ -480,7 +477,7 @@ as-is. They are also excluded when calling
> parse. So the evaluation results should always reflect what your pipeline will
> produce at runtime. If you want a frozen component to run (without updating)
> during training as well, so that downstream components can use its
-> **predictions**, you can add it to the list of
+> **predictions**, you should add it to the list of
> [`annotating_components`](/usage/training#annotating-components).
```ini
@@ -518,7 +515,7 @@ replace_listeners = ["model.tok2vec"]
-### Using predictions from preceding components {#annotating-components new="3.1"}
+### Using predictions from preceding components {id="annotating-components",version="3.1"}
By default, components are updated in isolation during training, which means
that they don't see the predictions of any earlier components in the pipeline. A
@@ -532,8 +529,7 @@ list of components. For example, the feature `DEP` from the parser could be used
as a tagger feature by including `DEP` in the tok2vec `attrs` and including
`parser` in `annotating_components`:
-```ini
-### config.cfg (excerpt) {highlight="7,12"}
+```ini {title="config.cfg (excerpt)",highlight="7,12"}
[nlp]
pipeline = ["parser", "tagger"]
@@ -555,8 +551,7 @@ pipeline is run. The config excerpt below shows how a frozen `ner` component and
a `sentencizer` can provide the required `doc.sents` and `doc.ents` for the
entity linker during training:
-```ini
-### config.cfg (excerpt)
+```ini {title="config.cfg (excerpt)"}
[nlp]
pipeline = ["sentencizer", "ner", "entity_linker"]
@@ -580,7 +575,7 @@ now-updated model to the predicted docs.
-### Using registered functions {#config-functions}
+### Using registered functions {id="config-functions"}
The training configuration defined in the config file doesn't have to only
consist of static values. Some settings can also be **functions**. For instance,
@@ -588,8 +583,7 @@ the `batch_size` can be a number that doesn't change, or a schedule, like a
sequence of compounding values, which has shown to be an effective trick (see
[Smith et al., 2017](https://arxiv.org/abs/1711.00489)).
-```ini
-### With static value
+```ini {title="With static value"}
[training]
batch_size = 128
```
@@ -612,8 +606,7 @@ from your configs.
> instance, a learning rate schedule can be provided as the an argument of an
> optimizer.
-```ini
-### With registered function
+```ini {title="With registered function"}
[training.batch_size]
@schedules = "compounding.v1"
start = 100
@@ -621,7 +614,7 @@ stop = 1000
compound = 1.001
```
-### Model architectures {#model-architectures}
+### Model architectures {id="model-architectures"}
> #### 💡 Model type annotations
>
@@ -659,7 +652,7 @@ different tasks. For example:
| [TransitionBasedParser](/api/architectures#TransitionBasedParser) | Build a [transition-based parser](https://explosion.ai/blog/parsing-english-in-python) model used in the default [`EntityRecognizer`](/api/entityrecognizer) and [`DependencyParser`](/api/dependencyparser). ~~Model[List[Docs], List[List[Floats2d]]]~~ |
| [TextCatEnsemble](/api/architectures#TextCatEnsemble) | Stacked ensemble of a bag-of-words model and a neural network model with an internal CNN embedding layer. Used in the default [`TextCategorizer`](/api/textcategorizer). ~~Model[List[Doc], Floats2d]~~ |
-### Metrics, training output and weighted scores {#metrics}
+### Metrics, training output and weighted scores {id="metrics"}
When you train a pipeline using the [`spacy train`](/api/cli#train) command,
you'll see a table showing the metrics after each pass over the data. The
@@ -721,7 +714,7 @@ still look good.
-## Custom functions {#custom-functions}
+## Custom functions {id="custom-functions"}
Registered functions in the training config files can refer to built-in
implementations, but you can also plug in fully **custom implementations**. All
@@ -730,7 +723,7 @@ with the name of the respective [registry](/api/top-level#registry), e.g.
`@spacy.registry.architectures`, and a string name to assign to your function.
Registering custom functions allows you to **plug in models** defined in PyTorch
or TensorFlow, make **custom modifications** to the `nlp` object, create custom
-optimizers or schedules, or **stream in data** and preprocesses it on the fly
+optimizers or schedules, or **stream in data** and preprocess it on the fly
while training.
Each custom function can have any number of arguments that are passed in via the
@@ -740,14 +733,14 @@ Each custom function can have any number of arguments that are passed in via the
given parameter is always explicitly set in the config, avoid setting a default
value for it.
-### Training with custom code {#custom-code}
+### Training with custom code {id="custom-code"}
-> ```cli
+> ```bash
> ### Training
> $ python -m spacy train config.cfg --code functions.py
> ```
>
-> ```cli
+> ```bash
> ### Packaging
> $ python -m spacy package ./model-best ./packages --code functions.py
> ```
@@ -765,7 +758,7 @@ any custom architectures, functions or
your pipeline and registered when it's loaded. See the documentation on
[saving and loading pipelines](/usage/saving-loading#models-custom) for details.
-#### Example: Modifying the nlp object {#custom-code-nlp-callbacks}
+#### Example: Modifying the nlp object {id="custom-code-nlp-callbacks"}
For many use cases, you don't necessarily want to implement the whole `Language`
subclass and language data from scratch – it's often enough to make a few small
@@ -799,8 +792,7 @@ stop word to the defaults:
> @callbacks = "customize_language_data"
> ```
-```python
-### functions.py {highlight="3,6"}
+```python {title="functions.py",highlight="3,6"}
import spacy
@spacy.registry.callbacks("customize_language_data")
@@ -836,8 +828,7 @@ we're adding the arguments `extra_stop_words` (a list of strings) and `debug`
> debug = true
> ```
-```python
-### functions.py {highlight="5,7-9"}
+```python {title="functions.py",highlight="5,7-9"}
from typing import List
import spacy
@@ -873,11 +864,11 @@ you can now run [`spacy train`](/api/cli#train) and point the argument `--code`
to your Python file. Before loading the config, spaCy will import the
`functions.py` module and your custom functions will be registered.
-```cli
+```bash
$ python -m spacy train config.cfg --output ./output --code ./functions.py
```
-#### Example: Modifying tokenizer settings {#custom-tokenizer}
+#### Example: Modifying tokenizer settings {id="custom-tokenizer"}
Use the `initialize.before_init` callback to modify the tokenizer settings when
training a new pipeline. Write a registered callback that modifies the tokenizer
@@ -892,8 +883,7 @@ settings and specify this callback in your config:
> @callbacks = "customize_tokenizer"
> ```
-```python
-### functions.py
+```python {title="functions.py"}
from spacy.util import registry, compile_suffix_regex
@registry.callbacks("customize_tokenizer")
@@ -912,7 +902,7 @@ def make_customize_tokenizer():
When training, provide the function above with the `--code` option:
-```cli
+```bash
$ python -m spacy train config.cfg --code ./functions.py
```
@@ -936,7 +926,7 @@ disk.
-#### Example: Custom logging function {#custom-logging}
+#### Example: Custom logging function {id="custom-logging"}
During training, the results of each step are passed to a logger function. By
default, these results are written to the console with the
@@ -966,8 +956,7 @@ tabular results to a file:
> log_path = "my_file.tab"
> ```
-```python
-### functions.py
+```python {title="functions.py"}
import sys
from typing import IO, Tuple, Callable, Dict, Any, Optional
import spacy
@@ -1005,7 +994,7 @@ def custom_logger(log_path):
return setup_logger
```
-#### Example: Custom batch size schedule {#custom-code-schedule}
+#### Example: Custom batch size schedule {id="custom-code-schedule"}
You can also implement your own batch size schedule to use during training. The
`@spacy.registry.schedules` decorator lets you register that function in the
@@ -1019,8 +1008,7 @@ You can also implement your own batch size schedule to use during training. The
> know that a config referencing `v1` means a different function than a config
> referencing `v2`.
-```python
-### functions.py
+```python {title="functions.py"}
import spacy
@spacy.registry.schedules("my_custom_schedule.v1")
@@ -1037,15 +1025,14 @@ settings in the block will be passed to the function as keyword arguments. Keep
in mind that the config shouldn't have any hidden defaults and all arguments on
the functions need to be represented in the config.
-```ini
-### config.cfg (excerpt)
+```ini {title="config.cfg (excerpt)"}
[training.batch_size]
@schedules = "my_custom_schedule.v1"
start = 2
factor = 1.005
```
-### Defining custom architectures {#custom-architectures}
+### Defining custom architectures {id="custom-architectures"}
Built-in pipeline components such as the tagger or named entity recognizer are
constructed with default neural network [models](/api/architectures). You can
@@ -1064,8 +1051,7 @@ for more details.
> output_width = 512
> ```
-```python
-### functions.py
+```python {title="functions.py"}
from typing import List
from thinc.types import Floats2d
from thinc.api import Model
@@ -1077,7 +1063,7 @@ def custom_neural_network(output_width: int) -> Model[List[Doc], List[Floats2d]]
return create_model(output_width)
```
-## Customizing the initialization {#initialization}
+## Customizing the initialization {id="initialization"}
When you start training a new model from scratch,
[`spacy train`](/api/cli#train) will call
@@ -1120,7 +1106,7 @@ because the component settings required for training (load data from an external
file) wouldn't match the component settings required at runtime (load what's
included with the saved `nlp` object and don't depend on external file).
-
+
@@ -1131,7 +1117,7 @@ initialization is implemented under the hood, see the usage guide on
-#### Initializing labels {#initialization-labels}
+#### Initializing labels {id="initialization-labels"}
Built-in pipeline components like the
[`EntityRecognizer`](/api/entityrecognizer) or
@@ -1157,7 +1143,7 @@ allow them to initialize faster.
> path = "corpus/labels/ner.json
> ```
-```cli
+```bash
$ python -m spacy init labels config.cfg ./corpus --paths.train ./corpus/train.spacy
```
@@ -1174,20 +1160,20 @@ should always let spaCy **auto-generate the labels** for you.
-## Data utilities {#data}
+## Data utilities {id="data"}
spaCy includes various features and utilities to make it easy to train models
using your own data, manage training and evaluation corpora, convert existing
annotations and configure data augmentation strategies for more robust models.
-### Converting existing corpora and annotations {#data-convert}
+### Converting existing corpora and annotations {id="data-convert"}
If you have training data in a standard format like `.conll` or `.conllu`, the
easiest way to convert it for use with spaCy is to run
[`spacy convert`](/api/cli#convert) and pass it a file and an output directory.
By default, the command will pick the converter based on the file extension.
-```cli
+```bash
$ python -m spacy convert ./train.gold.conll ./corpus
```
@@ -1215,8 +1201,7 @@ especially when packing multiple documents together. You can also create `Doc`
objects manually, so you can write your own custom logic to convert and store
existing annotations for use in spaCy.
-```python
-### Training data from Doc objects {highlight="6-9"}
+```python {title="Training data from Doc objects",highlight="6-9"}
import spacy
from spacy.tokens import Doc, DocBin
@@ -1230,7 +1215,7 @@ docbin.add(doc)
docbin.to_disk("./train.spacy")
```
-### Working with corpora {#data-corpora}
+### Working with corpora {id="data-corpora"}
> #### Example
>
@@ -1271,7 +1256,7 @@ By default, the training data is loaded into memory and shuffled before each
epoch. If the corpus is **too large to fit into memory** during training, stream
the corpus using a custom reader as described in the next section.
-### Custom data reading and batching {#custom-code-readers-batchers}
+### Custom data reading and batching {id="custom-code-readers-batchers"}
Some use-cases require **streaming in data** or manipulating datasets on the
fly, rather than generating all data beforehand and storing it to disk. Instead
@@ -1296,8 +1281,7 @@ as **config settings** – in this case, `source`.
> source = "s3://your_bucket/path/data.csv"
> ```
-```python
-### functions.py {highlight="7-8"}
+```python {title="functions.py",highlight="7-8"}
from typing import Callable, Iterator, List
import spacy
from spacy.training import Example
@@ -1354,8 +1338,7 @@ training should stop.
> max_steps = 2000
> ```
-```python
-### functions.py
+```python {title="functions.py"}
from typing import Callable, Iterable, Iterator
from spacy import util
import random
@@ -1418,8 +1401,7 @@ annotations are the same.
> size = 150
> ```
-```python
-### functions.py
+```python {title="functions.py"}
from typing import Callable, Iterable, Iterator, List
import spacy
from spacy.training import Example
@@ -1439,12 +1421,9 @@ def filter_batch(size: int) -> Callable[[Iterable[Example]], Iterator[List[Examp
return create_filtered_batches
```
-
+{/* TODO: Custom corpus class, Minibatching */}
-### Data augmentation {#data-augmentation}
+### Data augmentation {id="data-augmentation"}
Data augmentation is the process of applying small **modifications** to the
training data. It can be especially useful for punctuation and case replacement
@@ -1458,8 +1437,7 @@ your config. The built-in [`orth_variants`](/api/top-level#orth_variants)
augmenter creates a data augmentation callback that uses orth-variant
replacement.
-```ini
-### config.cfg (excerpt) {highlight="8,14"}
+```ini {title="config.cfg (excerpt)",highlight="8,14"}
[corpora.train]
@readers = "spacy.Corpus.v1"
path = ${paths.train}
@@ -1483,12 +1461,18 @@ typically loaded from a JSON file. There are two types of orth variant rules:
`"single"` for single tokens that should be replaced (e.g. hyphens) and
`"paired"` for pairs of tokens (e.g. quotes).
-
-```json
-### orth_variants.json
+```json {title="orth_variants.json"}
{
"single": [{ "tags": ["NFP"], "variants": ["…", "..."] }],
- "paired": [{ "tags": ["``", "''"], "variants": [["'", "'"], ["‘", "’"]] }]
+ "paired": [
+ {
+ "tags": ["``", "''"],
+ "variants": [
+ ["'", "'"],
+ ["‘", "’"]
+ ]
+ }
+ ]
}
```
@@ -1511,7 +1495,7 @@ to apply it to the **training corpus**, not the development data.
-#### Writing custom data augmenters {#data-augmentation-custom}
+#### Writing custom data augmenters {id="data-augmentation-custom"}
Using the [`@spacy.augmenters`](/api/top-level#registry) registry, you can also
register your own data augmentation callbacks. The callback should be a function
@@ -1572,11 +1556,11 @@ token-based annotations like the dependency parse or entity labels, you'll need
to take care to adjust the `Example` object so its annotations match and remain
valid.
-## Parallel & distributed training with Ray {#parallel-training}
+## Parallel & distributed training with Ray {id="parallel-training"}
> #### Installation
>
-> ```cli
+> ```bash
> $ pip install -U %%SPACY_PKG_NAME[ray]%%SPACY_PKG_FLAGS
> # Check that the CLI is registered
> $ python -m spacy ray --help
@@ -1602,7 +1586,7 @@ The [`spacy ray train`](/api/cli#ray-train) command follows the same API as
setup. You can optionally set the `--address` option to point to your Ray
cluster. If it's not set, Ray will run locally.
-```cli
+```bash
python -m spacy ray train config.cfg --n-workers 2
```
@@ -1614,7 +1598,7 @@ training with Ray.
-### How parallel training works {#parallel-training-details}
+### How parallel training works {id="parallel-training-details"}
Each worker receives a shard of the **data** and builds a copy of the **model
and optimizer** from the [`config.cfg`](#config). It also has a communication
@@ -1623,7 +1607,7 @@ each worker is given ownership of a subset of the parameter arrays. Every
parameter array is owned by exactly one worker, and the workers are given a
mapping so they know which worker owns which parameter.
-
+
As training proceeds, every worker will be computing gradients for **all** of
the model parameters. When they compute gradients for parameters they don't own,
@@ -1643,7 +1627,7 @@ useful for spaCy, because spaCy is often trained on long documents, which means
gradient descent inefficient, because if one batch is slow, all of the other
workers are stuck waiting for it to complete before they can continue.
-## Internal training API {#api}
+## Internal training API {id="api"}
@@ -1657,7 +1641,7 @@ typically give you everything you need to train fully custom pipelines with
-### Training from a Python script {#api-train new="3.2"}
+### Training from a Python script {id="api-train",version="3.2"}
If you want to run the training from a Python script instead of using the
[`spacy train`](/api/cli#train) CLI command, you can call into the
@@ -1671,7 +1655,7 @@ from spacy.cli.train import train
train("./config.cfg", overrides={"paths.train": "./train.spacy", "paths.dev": "./dev.spacy"})
```
-### Internal training loop API {#api-loop}
+### Internal training loop API {id="api-loop"}
@@ -1762,8 +1746,7 @@ of being dropped.
> - [`nlp.to_disk`](/api/language#to_disk): Save the updated pipeline to a
> directory.
-```python
-### Example training loop
+```python {title="Example training loop"}
optimizer = nlp.initialize()
for itn in range(100):
random.shuffle(train_data)
diff --git a/website/docs/usage/v2-1.md b/website/docs/usage/v2-1.mdx
similarity index 94%
rename from website/docs/usage/v2-1.md
rename to website/docs/usage/v2-1.mdx
index 500e43803..261525d0f 100644
--- a/website/docs/usage/v2-1.md
+++ b/website/docs/usage/v2-1.mdx
@@ -6,7 +6,7 @@ menu:
- ['Backwards Incompatibilities', 'incompat']
---
-## New Features {#features hidden="true"}
+## New Features {id="features",hidden="true"}
spaCy v2.1 has focussed primarily on stability and performance, solidifying the
design changes introduced in [v2.0](/usage/v2). As well as smaller models,
@@ -16,7 +16,7 @@ for some exciting new NLP innovations. For the full changelog, see the
For more details and a behind-the-scenes look at the new release,
[see our blog post](https://explosion.ai/blog/spacy-v2-1).
-### BERT/ULMFit/Elmo-style pre-training {#pretraining tag="experimental"}
+### BERT/ULMFit/Elmo-style pre-training {id="pretraining",tag="experimental"}
> #### Example
>
@@ -41,7 +41,7 @@ it.
-### Extended match pattern API {#matcher-api}
+### Extended match pattern API {id="matcher-api"}
> #### Example
>
@@ -69,7 +69,7 @@ values.
-### Easy rule-based entity recognition {#entity-ruler}
+### Easy rule-based entity recognition {id="entity-ruler"}
> #### Example
>
@@ -93,7 +93,7 @@ flexibility.
-### Phrase matching with other attributes {#phrasematcher}
+### Phrase matching with other attributes {id="phrasematcher"}
> #### Example
>
@@ -117,7 +117,7 @@ or `POS` for finding sequences of the same part-of-speech tags.
-### Retokenizer for merging and splitting {#retokenizer}
+### Retokenizer for merging and splitting {id="retokenizer"}
> #### Example
>
@@ -144,7 +144,7 @@ deprecated.
-### Components and languages via entry points {#entry-points}
+### Components and languages via entry points {id="entry-points"}
> #### Example
>
@@ -171,7 +171,7 @@ is required.
-### Improved documentation {#docs}
+### Improved documentation {id="docs"}
Although it looks pretty much the same, we've rebuilt the entire documentation
using [Gatsby](https://www.gatsbyjs.org/) and [MDX](https://mdxjs.com/). It's
@@ -180,9 +180,9 @@ entirely **in Markdown**, without having to compromise on easy-to-use custom UI
components. We're hoping that the Markdown source will make it even easier to
contribute to the documentation. For more details, check out the
[styleguide](/styleguide) and
-[source](https://github.com/explosion/spacy/tree/v2.x/website). While
-converting the pages to Markdown, we've also fixed a bunch of typos, improved
-the existing pages and added some new content:
+[source](https://github.com/explosion/spacy/tree/v2.x/website). While converting
+the pages to Markdown, we've also fixed a bunch of typos, improved the existing
+pages and added some new content:
- **Usage Guide:** [Rule-based Matching](/usage/rule-based-matching) How to
use the `Matcher`, `PhraseMatcher` and the new `EntityRuler`, and write
@@ -200,7 +200,7 @@ the existing pages and added some new content:
- **API:** [`Sentencizer`](/api/sentencizer)
- **API:** [Pipeline functions](/api/pipeline-functions)
-## Backwards incompatibilities {#incompat}
+## Backwards incompatibilities {id="incompat"}
diff --git a/website/docs/usage/v2-2.md b/website/docs/usage/v2-2.mdx
similarity index 97%
rename from website/docs/usage/v2-2.md
rename to website/docs/usage/v2-2.mdx
index dd7325a9c..84129657d 100644
--- a/website/docs/usage/v2-2.md
+++ b/website/docs/usage/v2-2.mdx
@@ -7,7 +7,7 @@ menu:
- ['Migrating from v2.1', 'migrating']
---
-## New Features {#features hidden="true"}
+## New Features {id="features",hidden="true"}
spaCy v2.2 features improved statistical models, new pretrained models for
Norwegian and Lithuanian, better Dutch NER, as well as a new mechanism for
@@ -22,7 +22,7 @@ full changelog, see the
For more details and a behind-the-scenes look at the new release,
[see our blog post](https://explosion.ai/blog/spacy-v2-2).
-### Better pretrained models and more languages {#models}
+### Better pretrained models and more languages {id="models"}
> #### Example
>
@@ -46,7 +46,7 @@ overall. We've also added new core models for [Norwegian](/models/nb) (MIT) and
-### Text classification scores and CLI training {#train-textcat-cli}
+### Text classification scores and CLI training {id="train-textcat-cli"}
> #### Example
>
@@ -106,7 +106,7 @@ processing.
-### Serializable lookup tables and smaller installation {#lookups}
+### Serializable lookup tables and smaller installation {id="lookups"}
> #### Example
>
@@ -140,7 +140,7 @@ languages that don't yet ship with pretrained models.
-### CLI command to debug and validate training data {#debug-data}
+### CLI command to debug and validate training data {id="debug-data"}
> #### Example
>
@@ -300,7 +300,7 @@ will not be available.
-## Backwards incompatibilities {#incompat}
+## Backwards incompatibilities {id="incompat"}
@@ -379,7 +379,7 @@ check if all of your models are up to date, you can run the
list of dicts. This is mostly internals, but if your code used
`nlp.meta["sources"]`, you might have to update it.
-### Migrating from spaCy 2.1 {#migrating}
+### Migrating from spaCy 2.1 {id="migrating"}
#### Lemmatization data and lookup tables
@@ -389,8 +389,7 @@ with only tokenizers, you now need to install that data explicitly via
setup is required – the package just needs to be installed in the same
environment as spaCy.
-```python
-### {highlight="3-4"}
+```python {highlight="3-4"}
nlp = Turkish()
doc = nlp("Bu bir cümledir.")
# 🚨 This now requires the lookups data to be installed explicitly
diff --git a/website/docs/usage/v2-3.md b/website/docs/usage/v2-3.mdx
similarity index 98%
rename from website/docs/usage/v2-3.md
rename to website/docs/usage/v2-3.mdx
index 075e1ce81..33315259a 100644
--- a/website/docs/usage/v2-3.md
+++ b/website/docs/usage/v2-3.mdx
@@ -7,7 +7,7 @@ menu:
- ['Migrating from v2.2', 'migrating']
---
-## New Features {#features hidden="true"}
+## New Features {id="features",hidden="true"}
spaCy v2.3 features new pretrained models for five languages, word vectors for
all language models, and decreased model size and loading times for models with
@@ -19,7 +19,7 @@ Model packages with vectors are about **2×** smaller on disk and load
For more details and a behind-the-scenes look at the new release,
[see our blog post](https://explosion.ai/blog/spacy-v2-3).
-### Expanded model families with vectors {#models}
+### Expanded model families with vectors {id="models"}
> #### Example
>
@@ -45,7 +45,7 @@ and Dutch has been extended to include both UD Dutch Alpino and LassySmall.
-### Chinese {#chinese}
+### Chinese {id="chinese"}
> #### Example
>
@@ -77,7 +77,7 @@ Python 3.8.
-### Japanese {#japanese}
+### Japanese {id="japanese"}
The updated Japanese language class switches to
[`SudachiPy`](https://github.com/WorksApplications/SudachiPy) for word
@@ -102,7 +102,7 @@ installing spaCy for Japanese, which is now possible with a single command:
- [`spacy train`](/api/cli#train) on GPU restricts the CPU timing evaluation to
the first iteration
-## Backwards incompatibilities {#incompat}
+## Backwards incompatibilities {id="incompat"}
@@ -140,7 +140,7 @@ the [`spacy validate`](/api/cli#validate) command.
spaCy's tokenization and Universal Dependencies multi-word tokens used for
contractions.
-### Migrating from spaCy 2.2 {#migrating}
+### Migrating from spaCy 2.2 {id="migrating"}
#### Tokenizer settings
diff --git a/website/docs/usage/v2.md b/website/docs/usage/v2.mdx
similarity index 95%
rename from website/docs/usage/v2.md
rename to website/docs/usage/v2.mdx
index 210565c11..d40126e26 100644
--- a/website/docs/usage/v2.md
+++ b/website/docs/usage/v2.mdx
@@ -17,7 +17,7 @@ spaCy, or just want to brush up on some NLP basics and the details of the
library, check out the [spaCy 101 guide](/usage/spacy-101) that explains the
most important concepts with examples and illustrations.
-## Summary {#summary}
+## Summary {id="summary"}
@@ -73,12 +73,12 @@ differentiable. Even if you don't have explicitly annotated data, you can update
spaCy using all the **latest deep learning tricks** like adversarial training,
noise contrastive estimation or reinforcement learning.
-## New features {#features}
+## New features {id="features"}
This section contains an overview of the most important **new features and
improvements**. The [API docs](/api) include additional deprecation notes.
-### Convolutional neural network models {#features-models}
+### Convolutional neural network models {id="features-models"}
> #### Example
>
@@ -109,7 +109,7 @@ process.
-### Improved processing pipelines {#features-pipelines}
+### Improved processing pipelines {id="features-pipelines"}
> #### Example
>
@@ -130,7 +130,7 @@ write any **attributes, properties and methods** to the `Doc`, `Token` and
`Span`. You can add data, implement new features, integrate other libraries with
spaCy or plug in your own machine learning models.
-
+
@@ -143,7 +143,7 @@ spaCy or plug in your own machine learning models.
-### Text classification {#features-text-classification}
+### Text classification {id="features-text-classification"}
> #### Example
>
@@ -172,7 +172,7 @@ network to assign position-sensitive vectors to each word in the document.
-### Hash values instead of integer IDs {#features-hash-ids}
+### Hash values instead of integer IDs {id="features-hash-ids"}
> #### Example
>
@@ -201,7 +201,7 @@ available via `token.orth`.
-### Improved word vectors support {#features-vectors}
+### Improved word vectors support {id="features-vectors"}
> #### Example
>
@@ -231,7 +231,7 @@ you set the `--prune-vectors` flag. Otherwise, you can use the new
-### Saving, loading and serialization {#features-serializer}
+### Saving, loading and serialization {id="features-serializer"}
> #### Example
>
@@ -266,7 +266,7 @@ the class directly, e.g. `from spacy.lang.en import English` or use
-### displaCy visualizer with Jupyter support {#features-displacy}
+### displaCy visualizer with Jupyter support {id="features-displacy"}
> #### Example
>
@@ -291,7 +291,7 @@ notebook.
-### Improved language data and lazy loading {#features-language}
+### Improved language data and lazy loading {id="features-language"}
Language-specific data now lives in its own submodule, `spacy.lang`. Languages
are lazy-loaded, i.e. only loaded when you import a `Language` class, or load a
@@ -308,7 +308,7 @@ lookup-based lemmatization – and **many new languages**!
-### Revised matcher API and phrase matcher {#features-matcher}
+### Revised matcher API and phrase matcher {id="features-matcher"}
> #### Example
>
@@ -338,7 +338,7 @@ patterns.
-## Backwards incompatibilities {#incompat}
+## Backwards incompatibilities {id="incompat"}
The following modules, classes and methods have changed between v1.x and v2.0.
@@ -373,7 +373,7 @@ The following modules, classes and methods have changed between v1.x and v2.0.
| `Doc.read_bytes` | [`Doc.to_bytes`](/api/doc#to_bytes) [`Doc.from_bytes`](/api/doc#from_bytes) [`Doc.to_disk`](/api/doc#to_disk) [`Doc.from_disk`](/api/doc#from_disk) |
| `Token.is_ancestor_of` | [`Token.is_ancestor`](/api/token#is_ancestor) |
-### Deprecated {#deprecated}
+### Deprecated {id="deprecated"}
The following methods are deprecated. They can still be used, but should be
replaced.
@@ -383,7 +383,7 @@ replaced.
| `Tokenizer.tokens_from_list` | [`Doc`](/api/doc) |
| `Span.sent_start` | [`Span.is_sent_start`](/api/span#is_sent_start) |
-## Migrating from spaCy 1.x {#migrating}
+## Migrating from spaCy 1.x {id="migrating"}
Because we'e made so many architectural changes to the library, we've tried to
**keep breaking changes to a minimum**. A lot of projects follow the philosophy
@@ -403,7 +403,7 @@ v2.0.
-### Document processing {#migrating-document-processing}
+### Document processing {id="migrating-document-processing"}
The [`Language.pipe`](/api/language#pipe) method allows spaCy to batch
documents, which brings a **significant performance advantage** in v2.0. The new
@@ -421,7 +421,7 @@ To make usage easier, there's now a boolean `as_tuples` keyword argument, that
lets you pass in an iterator of `(text, context)` pairs, so you can get back an
iterator of `(doc, context)` tuples.
-### Saving, loading and serialization {#migrating-saving-loading}
+### Saving, loading and serialization {id="migrating-saving-loading"}
Double-check all calls to `spacy.load()` and make sure they don't use the `path`
keyword argument. If you're only loading in binary data and not a model package
@@ -451,7 +451,7 @@ If you've trained models with input from v1.x, you'll need to **retrain them**
with spaCy v2.0. All previous models will not be compatible with the new
version.
-### Processing pipelines and language data {#migrating-languages}
+### Processing pipelines and language data {id="migrating-languages"}
If you're importing language data or `Language` classes, make sure to change
your import statements to import from `spacy.lang`. If you've added your own
@@ -496,7 +496,7 @@ import and instantiate them directly – but it's more convenient to use the new
+ nlp.add_pipe(tagger, first=True)
```
-### Training {#migrating-training}
+### Training {id="migrating-training"}
All built-in pipeline components are now subclasses of [`Pipe`](/api/pipe),
fully trainable and serializable, and follow the same API. Instead of updating
@@ -525,7 +525,7 @@ training.
+ nlp.to_disk("/model")
```
-### Attaching custom data to the Doc {#migrating-doc}
+### Attaching custom data to the Doc {id="migrating-doc"}
Previously, you had to create a new container in order to attach custom data to
a `Doc` object. This often required converting the `Doc` objects to and from
@@ -561,7 +561,7 @@ own extension module.
+ meta = doc._.meta
```
-### Strings and hash values {#migrating-strings}
+### Strings and hash values {id="migrating-strings"}
The change from integer IDs to hash values may not actually affect your code
very much. However, if you're adding strings to the vocab manually, you now need
@@ -577,7 +577,7 @@ be sure that the string-to-hash mapping will always match across vocabularies.
+ other_nlp.vocab.strings["coffee"] # 3197928453018144401
```
-### Adding patterns and callbacks to the matcher {#migrating-matcher}
+### Adding patterns and callbacks to the matcher {id="migrating-matcher"}
If you're using the matcher, you can now add patterns in one step. This should
be easy to update – simply merge the ID, callback and patterns into one call to
diff --git a/website/docs/usage/v3-1.md b/website/docs/usage/v3-1.mdx
similarity index 89%
rename from website/docs/usage/v3-1.md
rename to website/docs/usage/v3-1.mdx
index 1bac8fd81..702932ad3 100644
--- a/website/docs/usage/v3-1.md
+++ b/website/docs/usage/v3-1.mdx
@@ -6,7 +6,7 @@ menu:
- ['Upgrading Notes', 'upgrading']
---
-## New Features {#features hidden="true"}
+## New Features {id="features",hidden="true"}
It's been great to see the adoption of the new spaCy v3, which introduced
[transformer-based](/usage/embeddings-transformers) pipelines, a new
@@ -18,7 +18,7 @@ component for predicting arbitrary and potentially overlapping spans, support
for partial incorrect annotations in the entity recognizer, new trained
pipelines for Catalan and Danish, as well as many bug fixes and improvements.
-### Using predicted annotations during training {#predicted-annotations-training}
+### Using predicted annotations during training {id="predicted-annotations-training"}
By default, components are updated in isolation during training, which means
that they don't see the predictions of any earlier components in the pipeline.
@@ -29,8 +29,7 @@ on the predicted docs during training. This makes it easy to use the predictions
of a previous component in the pipeline as features for a subsequent component,
e.g. the dependency labels in the tagger:
-```ini
-### config.cfg (excerpt) {highlight="7,12"}
+```ini {title="config.cfg (excerpt)",highlight="7,12"}
[nlp]
pipeline = ["parser", "tagger"]
@@ -52,7 +51,7 @@ as a feature for a subsequent tagger component in the pipeline.
-### SpanCategorizer for predicting arbitrary and overlapping spans {#spancategorizer tag="experimental"}
+### SpanCategorizer for predicting arbitrary and overlapping spans {id="spancategorizer",tag="experimental"}
A common task in applied NLP is extracting spans of texts from documents,
including longer phrases or nested expressions. Named entity recognition isn't
@@ -76,7 +75,11 @@ This project trains a span categorizer for Indonesian NER.
-[](https://support.prodi.gy/t/3861)
+
The upcoming version of our annotation tool [Prodigy](https://prodi.gy)
(currently available as a [pre-release](https://support.prodi.gy/t/3861) for all
@@ -86,7 +89,7 @@ for spaCy's `SpanCategorizer` component.
-### Update the entity recognizer with partial incorrect annotations {#negative-samples}
+### Update the entity recognizer with partial incorrect annotations {id="negative-samples"}
> #### config.cfg (excerpt)
>
@@ -116,9 +119,9 @@ train_doc.spans["incorrect_spans"] = [
]
```
-
+{/* TODO: more details and/or example project? */}
-### New pipeline packages for Catalan and Danish {#pipeline-packages}
+### New pipeline packages for Catalan and Danish {id="pipeline-packages"}
spaCy v3.1 adds 5 new pipeline packages, including a new core family for Catalan
and a new transformer-based pipeline for Danish using the
@@ -132,15 +135,15 @@ your own.
> contributions for Catalan and to Kenneth Enevoldsen for Danish. For additional
> Danish pipelines, check out [DaCy](https://github.com/KennethEnevoldsen/DaCy).
-| Package | Language | UPOS | Parser LAS | NER F |
-| ------------------------------------------------- | -------- | ---: | ---------: | -----: |
-| [`ca_core_news_sm`](/models/ca#ca_core_news_sm) | Catalan | 98.2 | 87.4 | 79.8 |
-| [`ca_core_news_md`](/models/ca#ca_core_news_md) | Catalan | 98.3 | 88.2 | 84.0 |
-| [`ca_core_news_lg`](/models/ca#ca_core_news_lg) | Catalan | 98.5 | 88.4 | 84.2 |
-| [`ca_core_news_trf`](/models/ca#ca_core_news_trf) | Catalan | 98.9 | 93.0 | 91.2 |
-| [`da_core_news_trf`](/models/da#da_core_news_trf) | Danish | 98.0 | 85.0 | 82.9 |
+| Package | Language | UPOS | Parser LAS | NER F |
+| ------------------------------------------------- | -------- | ---: | ---------: | ----: |
+| [`ca_core_news_sm`](/models/ca#ca_core_news_sm) | Catalan | 98.2 | 87.4 | 79.8 |
+| [`ca_core_news_md`](/models/ca#ca_core_news_md) | Catalan | 98.3 | 88.2 | 84.0 |
+| [`ca_core_news_lg`](/models/ca#ca_core_news_lg) | Catalan | 98.5 | 88.4 | 84.2 |
+| [`ca_core_news_trf`](/models/ca#ca_core_news_trf) | Catalan | 98.9 | 93.0 | 91.2 |
+| [`da_core_news_trf`](/models/da#da_core_news_trf) | Danish | 98.0 | 85.0 | 82.9 |
-### Resizable text classification architectures {#resizable-textcat}
+### Resizable text classification architectures {id="resizable-textcat"}
Previously, the [`TextCategorizer`](/api/textcategorizer) architectures could
not be resized, meaning that you couldn't add new labels to an already trained
@@ -148,18 +151,18 @@ model. In spaCy v3.1, the [TextCatCNN](/api/architectures#TextCatCNN) and
[TextCatBOW](/api/architectures#TextCatBOW) architectures are now resizable,
while ensuring that the predictions for the old labels remain the same.
-### CLI command to assemble pipeline from config {#assemble}
+### CLI command to assemble pipeline from config {id="assemble"}
The [`spacy assemble`](/api/cli#assemble) command lets you assemble a pipeline
from a config file without additional training. It can be especially useful for
creating a blank pipeline with a custom tokenizer, rule-based components or word
vectors.
-```cli
+```bash
$ python -m spacy assemble config.cfg ./output
```
-### Pretty pipeline package READMEs {#package-readme}
+### Pretty pipeline package READMEs {id="package-readme"}
The [`spacy package`](/api/cli#package) command now auto-generates a pretty
`README.md` based on the pipeline information defined in the `meta.json`. This
@@ -167,7 +170,7 @@ includes a table with a general overview, as well as the label scheme and
accuracy figures, if available. For an example, see the
[model releases](https://github.com/explosion/spacy-models/releases).
-### Support for streaming large or infinite corpora {#streaming-corpora}
+### Support for streaming large or infinite corpora {id="streaming-corpora"}
> #### config.cfg (excerpt)
>
@@ -193,7 +196,7 @@ available labels in every example. If necessary, you can use the
your components using a representative sample so the model can be initialized
correctly before training.
-### New lemmatizers for Catalan and Italian {#pos-lemmatizers}
+### New lemmatizers for Catalan and Italian {id="pos-lemmatizers"}
The trained pipelines for [Catalan](/models/ca) and [Italian](/models/it) now
include lemmatizers that use the predicted part-of-speech tags as part of the
@@ -203,7 +206,7 @@ sure you have the
[`spacy-lookups-data`](https://github.com/explosion/spacy-lookups-data) package
installed, which provides the relevant tables.
-### Upload your pipelines to the Hugging Face Hub {#huggingface-hub}
+### Upload your pipelines to the Hugging Face Hub {id="huggingface-hub"}
The [Hugging Face Hub](https://huggingface.co/) lets you upload models and share
them with others, and it now supports spaCy pipelines out-of-the-box. The new
@@ -218,7 +221,7 @@ details, files and interactive visualizers, as well as a direct URL to the wheel
file that you can install via `pip install`. For examples, check out the
[spaCy pipelines](https://huggingface.co/spacy) we've uploaded.
-```cli
+```bash
$ pip install spacy-huggingface-hub
$ huggingface-cli login
$ python -m spacy package ./en_ner_fashion ./output --build wheel
@@ -238,9 +241,9 @@ packaged model has changed. This makes it easy to deploy your models end-to-end.
-## Notes about upgrading from v3.0 {#upgrading}
+## Notes about upgrading from v3.0 {id="upgrading"}
-### Pipeline package version compatibility {#version-compat}
+### Pipeline package version compatibility {id="version-compat"}
> #### Using legacy implementations
>
@@ -280,7 +283,7 @@ In many cases (`spacy train`, `spacy.load()`), the new defaults will be filled
in automatically, but you'll need to fill in the new settings to run
[`debug config`](/api/cli#debug) and [`debug data`](/api/cli#debug-data).
-### Sourcing pipeline components with vectors {#source-vectors}
+### Sourcing pipeline components with vectors {id="source-vectors"}
If you're sourcing a pipeline component that requires static vectors (for
example, a tagger or parser from an `md` or `lg` pretrained pipeline), be sure
@@ -289,8 +292,7 @@ spaCy v3.0, a bug allowed vectors to be loaded implicitly through `source`,
however in v3.1 this setting must be provided explicitly as
`[initialize.vectors]`:
-```ini
-### config.cfg (excerpt)
+```ini {title="config.cfg (excerpt)"}
[components.ner]
source = "en_core_web_md"
@@ -312,7 +314,7 @@ vectors. If you are sourcing a rule-based component like an entity ruler or
lemmatizer that does not use the vectors as a model feature, then this warning
can be safely ignored.
-### Warnings {#warnings}
+### Warnings {id="warnings"}
Logger warnings have been converted to Python warnings. Use
[`warnings.filterwarnings`](https://docs.python.org/3/library/warnings.html#warnings.filterwarnings)
diff --git a/website/docs/usage/v3-2.md b/website/docs/usage/v3-2.mdx
similarity index 92%
rename from website/docs/usage/v3-2.md
rename to website/docs/usage/v3-2.mdx
index d1d45c7ba..b4a4ef672 100644
--- a/website/docs/usage/v3-2.md
+++ b/website/docs/usage/v3-2.mdx
@@ -6,7 +6,7 @@ menu:
- ['Upgrading Notes', 'upgrading']
---
-## New Features {#features hidden="true"}
+## New Features {id="features",hidden="true"}
spaCy v3.2 adds support for [`floret`](https://github.com/explosion/floret)
vectors, makes custom `Doc` creation and scoring easier, and includes many bug
@@ -26,31 +26,29 @@ $ pip install spacy[apple]
-### Registered scoring functions {#registered-scoring-functions}
+### Registered scoring functions {id="registered-scoring-functions"}
To customize the scoring, you can specify a scoring function for each component
in your config from the new [`scorers` registry](/api/top-level#registry):
-```ini
-### config.cfg (excerpt) {highlight="3"}
+```ini {title="config.cfg (excerpt)",highlight="3"}
[components.tagger]
factory = "tagger"
scorer = {"@scorers":"spacy.tagger_scorer.v1"}
```
-### Overwrite settings {#overwrite}
+### Overwrite settings {id="overwrite"}
Most pipeline components now include an `overwrite` setting in the config that
determines whether existing annotation in the `Doc` is preserved or overwritten:
-```ini
-### config.cfg (excerpt) {highlight="3"}
+```ini {title="config.cfg (excerpt)",highlight="3"}
[components.tagger]
factory = "tagger"
overwrite = false
```
-### Doc input for pipelines {#doc-input}
+### Doc input for pipelines {id="doc-input"}
[`nlp`](/api/language#call) and [`nlp.pipe`](/api/language#pipe) accept
[`Doc`](/api/doc) input, skipping the tokenizer if a `Doc` is provided instead
@@ -63,13 +61,13 @@ doc._.text_id = 500
doc = nlp(doc)
```
-### Support for floret vectors {#vectors}
+### Support for floret vectors {id="vectors"}
We recently published [`floret`](https://github.com/explosion/floret), an
extended version of [fastText](https://fasttext.cc) that combines fastText's
subwords with Bloom embeddings for compact, full-coverage vectors. The use of
subwords means that there are no OOV words and due to Bloom embeddings, the
-vector table can be kept very small at <100K entries. Bloom embeddings are
+vector table can be kept very small at \<100K entries. Bloom embeddings are
already used by [HashEmbed](https://thinc.ai/docs/api-layers#hashembed) in
[tok2vec](/api/architectures#tok2vec-arch) for compact spaCy models.
@@ -127,7 +125,7 @@ For the default project settings with 1M (3.3G) tokenized training texts and 50K
-### Updates for spacy-transformers v1.1 {#spacy-transformers}
+### Updates for spacy-transformers v1.1 {id="spacy-transformers"}
[`spacy-transformers`](https://github.com/explosion/spacy-transformers) v1.1 has
been refactored to improve serialization and support of inline transformer
@@ -147,7 +145,7 @@ such as `output_attentions`. Additional output is stored under
has been improved by streamlining allocations for tokenizer output and there is
new support for [mixed-precision training](/api/architectures#TransformerModel).
-### New transformer package for Japanese {#pipeline-packages}
+### New transformer package for Japanese {id="pipeline-packages"}
spaCy v3.2 adds a new transformer pipeline package for Japanese
[`ja_core_news_trf`](/models/ja#ja_core_news_trf), which uses the `basic`
@@ -155,7 +153,7 @@ pretokenizer instead of `mecab` to limit the number of dependencies required for
the pipeline. Thanks to Hiroshi Matsuda and the spaCy Japanese community for
their contributions!
-### Pipeline and language updates {#pipeline-updates}
+### Pipeline and language updates {id="pipeline-updates"}
- All Universal Dependencies training data has been updated to v2.8.
- The Catalan data, tokenizer and lemmatizer have been updated, thanks to Carlos
@@ -173,9 +171,9 @@ spaCy v3.2 also features a new Irish lemmatizer, support for `noun_chunks` in
Portuguese, improved `noun_chunks` for Spanish and additional updates for
Bulgarian, Catalan, Sinhala, Tagalog, Tigrinya and Vietnamese.
-## Notes about upgrading from v3.1 {#upgrading}
+## Notes about upgrading from v3.1 {id="upgrading"}
-### Pipeline package version compatibility {#version-compat}
+### Pipeline package version compatibility {id="version-compat"}
> #### Using legacy implementations
>
@@ -207,7 +205,7 @@ working as expected, you can update the spaCy version requirements in the
To update a config from spaCy v3.1 with the new v3.2 settings, run
[`init fill-config`](/api/cli#init-fill-config):
-```cli
+```bash
$ python -m spacy init fill-config config-v3.1.cfg config-v3.2.cfg
```
@@ -216,7 +214,7 @@ In many cases ([`spacy train`](/api/cli#train),
automatically, but you'll need to fill in the new settings to run
[`debug config`](/api/cli#debug) and [`debug data`](/api/cli#debug-data).
-## Notes about upgrading from spacy-transformers v1.0 {#upgrading-transformers}
+## Notes about upgrading from spacy-transformers v1.0 {id="upgrading-transformers"}
When you're loading a transformer pipeline package trained with
[`spacy-transformers`](https://github.com/explosion/spacy-transformers) v1.0
diff --git a/website/docs/usage/v3-3.mdx b/website/docs/usage/v3-3.mdx
new file mode 100644
index 000000000..d692475de
--- /dev/null
+++ b/website/docs/usage/v3-3.mdx
@@ -0,0 +1,249 @@
+---
+title: What's New in v3.3
+teaser: New features and how to upgrade
+menu:
+ - ['New Features', 'features']
+ - ['Upgrading Notes', 'upgrading']
+---
+
+## New features {id="features",hidden="true"}
+
+spaCy v3.3 improves the speed of core pipeline components, adds a new trainable
+lemmatizer, and introduces trained pipelines for Finnish, Korean and Swedish.
+
+### Speed improvements {id="speed"}
+
+v3.3 includes a slew of speed improvements:
+
+- Speed up parser and NER by using constant-time head lookups.
+- Support unnormalized softmax probabilities in `spacy.Tagger.v2` to speed up
+ inference for tagger, morphologizer, senter and trainable lemmatizer.
+- Speed up parser projectivization functions.
+- Replace `Ragged` with faster `AlignmentArray` in `Example` for training.
+- Improve `Matcher` speed.
+- Improve serialization speed for empty `Doc.spans`.
+
+For longer texts, the trained pipeline speeds improve **15%** or more in
+prediction. We benchmarked `en_core_web_md` (same components as in v3.2) and
+`de_core_news_md` (with the new trainable lemmatizer) across a range of text
+sizes on Linux (Intel Xeon W-2265) and OS X (M1) to compare spaCy v3.2 vs. v3.3:
+
+**Intel Xeon W-2265**
+
+| Model | Avg. Words/Doc | v3.2 Words/Sec | v3.3 Words/Sec | Diff |
+| :----------------------------------------------- | -------------: | -------------: | -------------: | -----: |
+| [`en_core_web_md`](/models/en#en_core_web_md) | 100 | 17292 | 17441 | 0.86% |
+| (=same components) | 1000 | 15408 | 16024 | 4.00% |
+| | 10000 | 12798 | 15346 | 19.91% |
+| [`de_core_news_md`](/models/de/#de_core_news_md) | 100 | 20221 | 19321 | -4.45% |
+| (+v3.3 trainable lemmatizer) | 1000 | 17480 | 17345 | -0.77% |
+| | 10000 | 14513 | 17036 | 17.38% |
+
+**Apple M1**
+
+| Model | Avg. Words/Doc | v3.2 Words/Sec | v3.3 Words/Sec | Diff |
+| ------------------------------------------------ | -------------: | -------------: | -------------: | -----: |
+| [`en_core_web_md`](/models/en#en_core_web_md) | 100 | 18272 | 18408 | 0.74% |
+| (=same components) | 1000 | 18794 | 19248 | 2.42% |
+| | 10000 | 15144 | 17513 | 15.64% |
+| [`de_core_news_md`](/models/de/#de_core_news_md) | 100 | 19227 | 19591 | 1.89% |
+| (+v3.3 trainable lemmatizer) | 1000 | 20047 | 20628 | 2.90% |
+| | 10000 | 15921 | 18546 | 16.49% |
+
+### Trainable lemmatizer {id="trainable-lemmatizer"}
+
+The new [trainable lemmatizer](/api/edittreelemmatizer) component uses
+[edit trees](https://explosion.ai/blog/edit-tree-lemmatizer) to transform tokens
+into lemmas. Try out the trainable lemmatizer with the
+[training quickstart](/usage/training#quickstart)!
+
+### displaCy support for overlapping spans and arcs {id="displacy"}
+
+displaCy now supports overlapping spans with a new
+[`span`](/usage/visualizers#span) style and multiple arcs with different labels
+between the same tokens for [`dep`](/usage/visualizers#dep) visualizations.
+
+Overlapping spans can be visualized for any spans key in `doc.spans`:
+
+```python
+import spacy
+from spacy import displacy
+from spacy.tokens import Span
+
+nlp = spacy.blank("en")
+text = "Welcome to the Bank of China."
+doc = nlp(text)
+doc.spans["custom"] = [Span(doc, 3, 6, "ORG"), Span(doc, 5, 6, "GPE")]
+displacy.serve(doc, style="span", options={"spans_key": "custom"})
+```
+
+
+
+## Additional features and improvements
+
+- Config comparisons with [`spacy debug diff-config`](/api/cli#debug-diff).
+- Span suggester debugging with
+ [`SpanCategorizer.set_candidates`](/api/spancategorizer#set_candidates).
+- Big endian support with
+ [`thinc-bigendian-ops`](https://github.com/andrewsi-z/thinc-bigendian-ops) and
+ updates to make `floret`, `murmurhash`, Thinc and spaCy endian neutral.
+- Initial support for Lower Sorbian and Upper Sorbian.
+- Language updates for English, French, Italian, Japanese, Korean, Norwegian,
+ Russian, Slovenian, Spanish, Turkish, Ukrainian and Vietnamese.
+- New noun chunks for Finnish.
+
+## Trained pipelines {id="pipelines"}
+
+### New trained pipelines {id="new-pipelines"}
+
+v3.3 introduces new CPU/CNN pipelines for Finnish, Korean and Swedish, which use
+the new trainable lemmatizer and
+[floret vectors](https://github.com/explosion/floret). Due to the use
+[Bloom embeddings](https://explosion.ai/blog/bloom-embeddings) and subwords, the
+pipelines have compact vectors with no out-of-vocabulary words.
+
+| Package | Language | UPOS | Parser LAS | NER F |
+| ----------------------------------------------- | -------- | ---: | ---------: | ----: |
+| [`fi_core_news_sm`](/models/fi#fi_core_news_sm) | Finnish | 92.5 | 71.9 | 75.9 |
+| [`fi_core_news_md`](/models/fi#fi_core_news_md) | Finnish | 95.9 | 78.6 | 80.6 |
+| [`fi_core_news_lg`](/models/fi#fi_core_news_lg) | Finnish | 96.2 | 79.4 | 82.4 |
+| [`ko_core_news_sm`](/models/ko#ko_core_news_sm) | Korean | 86.1 | 65.6 | 71.3 |
+| [`ko_core_news_md`](/models/ko#ko_core_news_md) | Korean | 94.7 | 80.9 | 83.1 |
+| [`ko_core_news_lg`](/models/ko#ko_core_news_lg) | Korean | 94.7 | 81.3 | 85.3 |
+| [`sv_core_news_sm`](/models/sv#sv_core_news_sm) | Swedish | 95.0 | 75.9 | 74.7 |
+| [`sv_core_news_md`](/models/sv#sv_core_news_md) | Swedish | 96.3 | 78.5 | 79.3 |
+| [`sv_core_news_lg`](/models/sv#sv_core_news_lg) | Swedish | 96.3 | 79.1 | 81.1 |
+
+### Pipeline updates {id="pipeline-updates"}
+
+The following languages switch from lookup or rule-based lemmatizers to the new
+trainable lemmatizer: Danish, Dutch, German, Greek, Italian, Lithuanian,
+Norwegian, Polish, Portuguese and Romanian. The overall lemmatizer accuracy
+improves for all of these pipelines, but be aware that the types of errors may
+look quite different from the lookup-based lemmatizers. If you'd prefer to
+continue using the previous lemmatizer, you can
+[switch from the trainable lemmatizer to a non-trainable lemmatizer](/models#design-modify).
+
+
+
+| Model | v3.2 Lemma Acc | v3.3 Lemma Acc |
+| ----------------------------------------------- | -------------: | -------------: |
+| [`da_core_news_md`](/models/da#da_core_news_md) | 84.9 | 94.8 |
+| [`de_core_news_md`](/models/de#de_core_news_md) | 73.4 | 97.7 |
+| [`el_core_news_md`](/models/el#el_core_news_md) | 56.5 | 88.9 |
+| [`fi_core_news_md`](/models/fi#fi_core_news_md) | - | 86.2 |
+| [`it_core_news_md`](/models/it#it_core_news_md) | 86.6 | 97.2 |
+| [`ko_core_news_md`](/models/ko#ko_core_news_md) | - | 90.0 |
+| [`lt_core_news_md`](/models/lt#lt_core_news_md) | 71.1 | 84.8 |
+| [`nb_core_news_md`](/models/nb#nb_core_news_md) | 76.7 | 97.1 |
+| [`nl_core_news_md`](/models/nl#nl_core_news_md) | 81.5 | 94.0 |
+| [`pl_core_news_md`](/models/pl#pl_core_news_md) | 87.1 | 93.7 |
+| [`pt_core_news_md`](/models/pt#pt_core_news_md) | 76.7 | 96.9 |
+| [`ro_core_news_md`](/models/ro#ro_core_news_md) | 81.8 | 95.5 |
+| [`sv_core_news_md`](/models/sv#sv_core_news_md) | - | 95.5 |
+
+
+
+In addition, the vectors in the English pipelines are deduplicated to improve
+the pruned vectors in the `md` models and reduce the `lg` model size.
+
+## Notes about upgrading from v3.2 {id="upgrading"}
+
+### Span comparisons
+
+Span comparisons involving ordering (`<`, `<=`, `>`, `>=`) now take all span
+attributes into account (start, end, label, and KB ID) so spans may be sorted in
+a slightly different order.
+
+### Whitespace annotation
+
+During training, annotation on whitespace tokens is handled in the same way as
+annotation on non-whitespace tokens in order to allow custom whitespace
+annotation.
+
+### Doc.from_docs
+
+[`Doc.from_docs`](/api/doc#from_docs) now includes `Doc.tensor` by default and
+supports excludes with an `exclude` argument in the same format as
+`Doc.to_bytes`. The supported exclude fields are `spans`, `tensor` and
+`user_data`.
+
+Docs including `Doc.tensor` may be quite a bit larger in RAM, so to exclude
+`Doc.tensor` as in v3.2:
+
+```diff
+-merged_doc = Doc.from_docs(docs)
++merged_doc = Doc.from_docs(docs, exclude=["tensor"])
+```
+
+### Using trained pipelines with floret vectors
+
+If you're running a new trained pipeline for Finnish, Korean or Swedish on new
+texts and working with `Doc` objects, you shouldn't notice any difference with
+floret vectors vs. default vectors.
+
+If you use vectors for similarity comparisons, there are a few differences,
+mainly because a floret pipeline doesn't include any kind of frequency-based
+word list similar to the list of in-vocabulary vector keys with default vectors.
+
+- If your workflow iterates over the vector keys, you should use an external
+ word list instead:
+
+ ```diff
+ - lexemes = [nlp.vocab[orth] for orth in nlp.vocab.vectors]
+ + lexemes = [nlp.vocab[word] for word in external_word_list]
+ ```
+
+- `Vectors.most_similar` is not supported because there's no fixed list of
+ vectors to compare your vectors to.
+
+### Pipeline package version compatibility {id="version-compat"}
+
+> #### Using legacy implementations
+>
+> In spaCy v3, you'll still be able to load and reference legacy implementations
+> via [`spacy-legacy`](https://github.com/explosion/spacy-legacy), even if the
+> components or architectures change and newer versions are available in the
+> core library.
+
+When you're loading a pipeline package trained with an earlier version of spaCy
+v3, you will see a warning telling you that the pipeline may be incompatible.
+This doesn't necessarily have to be true, but we recommend running your
+pipelines against your test suite or evaluation data to make sure there are no
+unexpected results.
+
+If you're using one of the [trained pipelines](/models) we provide, you should
+run [`spacy download`](/api/cli#download) to update to the latest version. To
+see an overview of all installed packages and their compatibility, you can run
+[`spacy validate`](/api/cli#validate).
+
+If you've trained your own custom pipeline and you've confirmed that it's still
+working as expected, you can update the spaCy version requirements in the
+[`meta.json`](/api/data-formats#meta):
+
+```diff
+- "spacy_version": ">=3.2.0,<3.3.0",
++ "spacy_version": ">=3.2.0,<3.4.0",
+```
+
+### Updating v3.2 configs
+
+To update a config from spaCy v3.2 with the new v3.3 settings, run
+[`init fill-config`](/api/cli#init-fill-config):
+
+```bash
+$ python -m spacy init fill-config config-v3.2.cfg config-v3.3.cfg
+```
+
+In many cases ([`spacy train`](/api/cli#train),
+[`spacy.load`](/api/top-level#spacy.load)), the new defaults will be filled in
+automatically, but you'll need to fill in the new settings to run
+[`debug config`](/api/cli#debug) and [`debug data`](/api/cli#debug-data).
+
+To see the speed improvements for the
+[`Tagger` architecture](/api/architectures#Tagger), edit your config to switch
+from `spacy.Tagger.v1` to `spacy.Tagger.v2` and then run `init fill-config`.
diff --git a/website/docs/usage/v3-4.mdx b/website/docs/usage/v3-4.mdx
new file mode 100644
index 000000000..c06db9dc2
--- /dev/null
+++ b/website/docs/usage/v3-4.mdx
@@ -0,0 +1,143 @@
+---
+title: What's New in v3.4
+teaser: New features and how to upgrade
+menu:
+ - ['New Features', 'features']
+ - ['Upgrading Notes', 'upgrading']
+---
+
+## New features {id="features",hidden="true"}
+
+spaCy v3.4 brings typing and speed improvements along with new vectors for
+English CNN pipelines and new trained pipelines for Croatian. This release also
+includes prebuilt linux aarch64 wheels for all spaCy dependencies distributed by
+Explosion.
+
+### Typing improvements {id="typing"}
+
+spaCy v3.4 supports pydantic v1.9 and mypy 0.950+ through extensive updates to
+types in Thinc v8.1.
+
+### Speed improvements {id="speed"}
+
+- For the parser, use C `saxpy`/`sgemm` provided by the `Ops` implementation in
+ order to use Accelerate through `thinc-apple-ops`.
+- Improved speed of vector lookups.
+- Improved speed for `Example.get_aligned_parse` and `Example.get_aligned`.
+
+## Additional features and improvements
+
+- Min/max `{n,m}` operator for `Matcher` patterns.
+- Language updates:
+ - Improve tokenization for Cyrillic combining diacritics.
+ - Improve English tokenizer exceptions for contractions with
+ this/that/these/those.
+- Updated `spacy project clone` to try both `main` and `master` branches by
+ default.
+- Added confidence threshold for named entity linker.
+- Improved handling of Typer optional default values for `init_config_cli`.
+- Added cycle detection in parser projectivization methods.
+- Added counts for NER labels in `debug data`.
+- Support for adding NVTX ranges to `TrainablePipe` components.
+- Support env variable `SPACY_NUM_BUILD_JOBS` to specify the number of build
+ jobs to run in parallel with `pip`.
+
+## Trained pipelines {id="pipelines"}
+
+### New trained pipelines {id="new-pipelines"}
+
+v3.4 introduces new CPU/CNN pipelines for Croatian, which use the trainable
+lemmatizer and [floret vectors](https://github.com/explosion/floret). Due to the
+use of [Bloom embeddings](https://explosion.ai/blog/bloom-embeddings) and
+subwords, the pipelines have compact vectors with no out-of-vocabulary words.
+
+| Package | UPOS | Parser LAS | NER F |
+| ----------------------------------------------- | ---: | ---------: | ----: |
+| [`hr_core_news_sm`](/models/hr#hr_core_news_sm) | 96.6 | 77.5 | 76.1 |
+| [`hr_core_news_md`](/models/hr#hr_core_news_md) | 97.3 | 80.1 | 81.8 |
+| [`hr_core_news_lg`](/models/hr#hr_core_news_lg) | 97.5 | 80.4 | 83.0 |
+
+### Pipeline updates {id="pipeline-updates"}
+
+All CNN pipelines have been extended with whitespace augmentation.
+
+The English CNN pipelines have new word vectors:
+
+| Package | Model Version | TAG | Parser LAS | NER F |
+| --------------------------------------------- | ------------- | ---: | ---------: | ----: |
+| [`en_core_web_md`](/models/en#en_core_web_md) | v3.3.0 | 97.3 | 90.1 | 84.6 |
+| [`en_core_web_md`](/models/en#en_core_web_md) | v3.4.0 | 97.2 | 90.3 | 85.5 |
+| [`en_core_web_lg`](/models/en#en_core_web_lg) | v3.3.0 | 97.4 | 90.1 | 85.3 |
+| [`en_core_web_lg`](/models/en#en_core_web_lg) | v3.4.0 | 97.3 | 90.2 | 85.6 |
+
+## Notes about upgrading from v3.3 {id="upgrading"}
+
+### Doc.has_vector
+
+`Doc.has_vector` now matches `Token.has_vector` and `Span.has_vector`: it
+returns `True` if at least one token in the doc has a vector rather than
+checking only whether the vocab contains vectors.
+
+### Using trained pipelines with floret vectors
+
+If you're using a trained pipeline for Croatian, Finnish, Korean or Swedish with
+new texts and working with `Doc` objects, you shouldn't notice any difference
+between floret vectors and default vectors.
+
+If you use vectors for similarity comparisons, there are a few differences,
+mainly because a floret pipeline doesn't include any kind of frequency-based
+word list similar to the list of in-vocabulary vector keys with default vectors.
+
+- If your workflow iterates over the vector keys, you should use an external
+ word list instead:
+
+ ```diff
+ - lexemes = [nlp.vocab[orth] for orth in nlp.vocab.vectors]
+ + lexemes = [nlp.vocab[word] for word in external_word_list]
+ ```
+
+- `Vectors.most_similar` is not supported because there's no fixed list of
+ vectors to compare your vectors to.
+
+### Pipeline package version compatibility {id="version-compat"}
+
+> #### Using legacy implementations
+>
+> In spaCy v3, you'll still be able to load and reference legacy implementations
+> via [`spacy-legacy`](https://github.com/explosion/spacy-legacy), even if the
+> components or architectures change and newer versions are available in the
+> core library.
+
+When you're loading a pipeline package trained with an earlier version of spaCy
+v3, you will see a warning telling you that the pipeline may be incompatible.
+This doesn't necessarily have to be true, but we recommend running your
+pipelines against your test suite or evaluation data to make sure there are no
+unexpected results.
+
+If you're using one of the [trained pipelines](/models) we provide, you should
+run [`spacy download`](/api/cli#download) to update to the latest version. To
+see an overview of all installed packages and their compatibility, you can run
+[`spacy validate`](/api/cli#validate).
+
+If you've trained your own custom pipeline and you've confirmed that it's still
+working as expected, you can update the spaCy version requirements in the
+[`meta.json`](/api/data-formats#meta):
+
+```diff
+- "spacy_version": ">=3.3.0,<3.4.0",
++ "spacy_version": ">=3.3.0,<3.5.0",
+```
+
+### Updating v3.3 configs
+
+To update a config from spaCy v3.3 with the new v3.4 settings, run
+[`init fill-config`](/api/cli#init-fill-config):
+
+```bash
+$ python -m spacy init fill-config config-v3.3.cfg config-v3.4.cfg
+```
+
+In many cases ([`spacy train`](/api/cli#train),
+[`spacy.load`](/api/top-level#spacy.load)), the new defaults will be filled in
+automatically, but you'll need to fill in the new settings to run
+[`debug config`](/api/cli#debug) and [`debug data`](/api/cli#debug-data).
diff --git a/website/docs/usage/v3-5.mdx b/website/docs/usage/v3-5.mdx
new file mode 100644
index 000000000..ac61338e3
--- /dev/null
+++ b/website/docs/usage/v3-5.mdx
@@ -0,0 +1,215 @@
+---
+title: What's New in v3.5
+teaser: New features and how to upgrade
+menu:
+ - ['New Features', 'features']
+ - ['Upgrading Notes', 'upgrading']
+---
+
+## New features {id="features",hidden="true"}
+
+spaCy v3.5 introduces three new CLI commands, `apply`, `benchmark` and
+`find-threshold`, adds fuzzy matching, provides improvements to our entity
+linking functionality, and includes a range of language updates and bug fixes.
+
+### New CLI commands {id="cli"}
+
+#### apply CLI
+
+The [`apply` CLI](/api/cli#apply) can be used to apply a pipeline to one or more
+`.txt`, `.jsonl` or `.spacy` input files, saving the annotated docs in a single
+`.spacy` file.
+
+```bash
+$ spacy apply en_core_web_sm my_texts/ output.spacy
+```
+
+#### benchmark CLI
+
+The [`benchmark` CLI](/api/cli#benchmark) has been added to extend the existing
+`evaluate` functionality with a wider range of profiling subcommands.
+
+The `benchmark accuracy` CLI is introduced as an alias for `evaluate`. The new
+`benchmark speed` CLI performs warmup rounds before measuring the speed in words
+per second on batches of randomly shuffled documents from the provided data.
+
+```bash
+$ spacy benchmark speed my_pipeline data.spacy
+```
+
+The output is the mean performance using batches (`nlp.pipe`) with a 95%
+confidence interval, e.g., profiling `en_core_web_sm` on CPU:
+
+```none
+Outliers: 2.0%, extreme outliers: 0.0%
+Mean: 18904.1 words/s (95% CI: -256.9 +244.1)
+```
+
+#### find-threshold CLI
+
+The [`find-threshold` CLI](/api/cli#find-threshold) runs a series of trials
+across threshold values from `0.0` to `1.0` and identifies the best threshold
+for the provided score metric.
+
+The following command runs 20 trials for the `spancat` component in
+`my_pipeline`, recording the `spans_sc_f` score for each value of the threshold
+`[components.spancat.threshold]` from `0.0` to `1.0`:
+
+```bash
+$ spacy find-threshold my_pipeline data.spacy spancat threshold spans_sc_f --n_trials 20
+```
+
+The `find-threshold` CLI can be used with `textcat_multilabel`, `spancat` and
+custom components with thresholds that are applied while predicting or scoring.
+
+### Fuzzy matching {id="fuzzy"}
+
+New `FUZZY` operators support [fuzzy matching](/usage/rule-based-matching#fuzzy)
+with the `Matcher`. By default, the `FUZZY` operator allows a Levenshtein edit
+distance of 2 and up to 30% of the pattern string length. `FUZZY1`..`FUZZY9` can
+be used to specify the exact number of allowed edits.
+
+```python
+# Match lowercase with fuzzy matching (allows up to 3 edits)
+pattern = [{"LOWER": {"FUZZY": "definitely"}}]
+
+# Match custom attribute values with fuzzy matching (allows up to 3 edits)
+pattern = [{"_": {"country": {"FUZZY": "Kyrgyzstan"}}}]
+
+# Match with exact Levenshtein edit distance limits (allows up to 4 edits)
+pattern = [{"_": {"country": {"FUZZY4": "Kyrgyzstan"}}}]
+```
+
+Note that `FUZZY` uses Levenshtein edit distance rather than Damerau-Levenshtein
+edit distance, so a transposition like `teh` for `the` counts as two edits, one
+insertion and one deletion.
+
+If you'd prefer an alternate fuzzy matching algorithm, you can provide your own
+custom method to the `Matcher` or as a config option for an entity ruler and
+span ruler.
+
+### FUZZY and REGEX with lists {id="fuzzy-regex-lists"}
+
+The `FUZZY` and `REGEX` operators are also now supported for lists with `IN` and
+`NOT_IN`:
+
+```python
+pattern = [{"TEXT": {"FUZZY": {"IN": ["awesome", "cool", "wonderful"]}}}]
+pattern = [{"TEXT": {"REGEX": {"NOT_IN": ["^awe(some)?$", "^wonder(ful)?"]}}}]
+```
+
+### Entity linking generalization {id="el"}
+
+The knowledge base used for entity linking is now easier to customize and has a
+new default implementation [`InMemoryLookupKB`](/api/inmemorylookupkb).
+
+### Additional features and improvements {id="additional-features-and-improvements"}
+
+- Language updates:
+ - Extended support for Slovenian
+ - Fixed lookup fallback for French and Catalan lemmatizers
+ - Switch Russian and Ukrainian lemmatizers to `pymorphy3`
+ - Support for editorial punctuation in Ancient Greek
+ - Update to Russian tokenizer exceptions
+ - Small fix for Dutch stop words
+- Allow up to `typer` v0.7.x, `mypy` 0.990 and `typing_extensions` v4.4.x.
+- New `spacy.ConsoleLogger.v3` with expanded progress
+ [tracking](/api/top-level#ConsoleLogger).
+- Improved scoring behavior for `textcat` with `spacy.textcat_scorer.v2` and
+ `spacy.textcat_multilabel_scorer.v2`.
+- Updates so that downstream components can train properly on a frozen `tok2vec`
+ or `transformer` layer.
+- Allow interpolation of variables in directory names in projects.
+- Support for local file system [remotes](/usage/projects#remote) for projects.
+- Improve UX around `displacy.serve` when the default port is in use.
+- Optional `before_update` callback that is invoked at the start of each
+ [training step](/api/data-formats#config-training).
+- Improve performance of `SpanGroup` and fix typing issues for `SpanGroup` and
+ `Span` objects.
+- Patch a
+ [security vulnerability](https://github.com/advisories/GHSA-gw9q-c7gh-j9vm) in
+ extracting tar files.
+- Add equality definition for `Vectors`.
+- Ensure `Vocab.to_disk` respects the exclude setting for `lookups` and
+ `vectors`.
+- Correctly handle missing annotations in the edit tree lemmatizer.
+
+### Trained pipeline updates {id="pipelines"}
+
+- The CNN pipelines add `IS_SPACE` as a `tok2vec` feature for `tagger` and
+ `morphologizer` components to improve tagging of non-whitespace vs. whitespace
+ tokens.
+- The transformer pipelines require `spacy-transformers` v1.2, which uses the
+ exact alignment from `tokenizers` for fast tokenizers instead of the heuristic
+ alignment from `spacy-alignments`. For all trained pipelines except
+ `ja_core_news_trf`, the alignments between spaCy tokens and transformer tokens
+ may be slightly different. More details about the `spacy-transformers` changes
+ in the
+ [v1.2.0 release notes](https://github.com/explosion/spacy-transformers/releases/tag/v1.2.0).
+
+## Notes about upgrading from v3.4 {id="upgrading"}
+
+### Validation of textcat values {id="textcat-validation"}
+
+An error is now raised when unsupported values are given as input to train a
+`textcat` or `textcat_multilabel` model - ensure that values are `0.0` or `1.0`
+as explained in the [docs](/api/textcategorizer#assigned-attributes).
+
+### Updated scorers for tokenization and textcat {id="scores"}
+
+We fixed a bug that inflated the `token_acc` scores in v3.0-v3.4. The reported
+`token_acc` will drop from v3.4 to v3.5, but if `token_p/r/f` stay the same,
+your tokenization performance has not changed from v3.4.
+
+For new `textcat` or `textcat_multilabel` configs, the new default `v2` scorers:
+
+- ignore `threshold` for `textcat`, so the reported `cats_p/r/f` may increase
+ slightly in v3.5 even though the underlying predictions are unchanged
+- report the performance of only the **final** `textcat` or `textcat_multilabel`
+ component in the pipeline by default
+- allow custom scorers to be used to score multiple `textcat` and
+ `textcat_multilabel` components with `Scorer.score_cats` by restricting the
+ evaluation to the component's provided labels
+
+### Pipeline package version compatibility {id="version-compat"}
+
+> #### Using legacy implementations
+>
+> In spaCy v3, you'll still be able to load and reference legacy implementations
+> via [`spacy-legacy`](https://github.com/explosion/spacy-legacy), even if the
+> components or architectures change and newer versions are available in the
+> core library.
+
+When you're loading a pipeline package trained with an earlier version of spaCy
+v3, you will see a warning telling you that the pipeline may be incompatible.
+This doesn't necessarily have to be true, but we recommend running your
+pipelines against your test suite or evaluation data to make sure there are no
+unexpected results.
+
+If you're using one of the [trained pipelines](/models) we provide, you should
+run [`spacy download`](/api/cli#download) to update to the latest version. To
+see an overview of all installed packages and their compatibility, you can run
+[`spacy validate`](/api/cli#validate).
+
+If you've trained your own custom pipeline and you've confirmed that it's still
+working as expected, you can update the spaCy version requirements in the
+[`meta.json`](/api/data-formats#meta):
+
+```diff
+- "spacy_version": ">=3.4.0,<3.5.0",
++ "spacy_version": ">=3.4.0,<3.6.0",
+```
+
+### Updating v3.4 configs
+
+To update a config from spaCy v3.4 with the new v3.5 settings, run
+[`init fill-config`](/api/cli#init-fill-config):
+
+```cli
+$ python -m spacy init fill-config config-v3.4.cfg config-v3.5.cfg
+```
+
+In many cases ([`spacy train`](/api/cli#train),
+[`spacy.load`](/api/top-level#spacy.load)), the new defaults will be filled in
+automatically, but you'll need to fill in the new settings to run
+[`debug config`](/api/cli#debug) and [`debug data`](/api/cli#debug-data).
diff --git a/website/docs/usage/v3.md b/website/docs/usage/v3.mdx
similarity index 94%
rename from website/docs/usage/v3.md
rename to website/docs/usage/v3.mdx
index 980f06172..7e7548d6a 100644
--- a/website/docs/usage/v3.md
+++ b/website/docs/usage/v3.mdx
@@ -8,25 +8,13 @@ menu:
- ['Migrating from v2.x', 'migrating']
---
-## Summary {#summary hidden="true"}
+## Summary {id="summary",hidden="true"}
> #### 📖 Looking for the old docs?
>
> To help you make the transition from v2.x to v3.0, we've uploaded the old
> website to [**v2.spacy.io**](https://v2.spacy.io/docs).
-
-
-Want to make the transition from spaCy v2 to spaCy v3 as smooth as possible for
-you and your organization? We're now offering commercial **migration support**
-for your spaCy pipelines! We've put a lot of work into making it easy to upgrade
-your existing code and training workflows – but custom projects may always need
-some custom work, especially when it comes to taking advantage of the new
-capabilities.
-[**Details & application →**](https://form.typeform.com/to/vMs2zSjM)
-
-
-
@@ -65,7 +53,7 @@ to clone and adapt best-practice projects for your own use cases.
-## New Features {#features}
+## New Features {id="features"}
This section contains an overview of the most important **new features and
improvements**. The [API docs](/api) include additional deprecation notes. New
@@ -82,11 +70,11 @@ tag 3.
-### Transformer-based pipelines {#features-transformers}
+### Transformer-based pipelines {id="features-transformers"}
> #### Example
>
-> ```cli
+> ```bash
> $ python -m spacy download en_core_web_trf
> ```
@@ -98,13 +86,11 @@ transformer support interoperates with [PyTorch](https://pytorch.org) and the
[HuggingFace `transformers`](https://huggingface.co/transformers/) library,
giving you access to thousands of pretrained models for your pipelines.
-
-
-import Benchmarks from 'usage/\_benchmarks-models.md'
+
-#### New trained transformer-based pipelines {#features-transformers-pipelines}
+#### New trained transformer-based pipelines {id="features-transformers-pipelines"}
> #### Notes on model capabilities
>
@@ -116,7 +102,7 @@ import Benchmarks from 'usage/\_benchmarks-models.md'
> corpus that had both syntactic and entity annotations, so the transformer
> models for those languages do not include NER.
-| Package | Language | Transformer | Tagger | Parser | NER |
+| Package | Language | Transformer | Tagger | Parser | NER |
| ------------------------------------------------ | -------- | --------------------------------------------------------------------------------------------- | -----: | -----: | ---: |
| [`en_core_web_trf`](/models/en#en_core_web_trf) | English | [`roberta-base`](https://huggingface.co/roberta-base) | 97.8 | 95.2 | 89.9 |
| [`de_dep_news_trf`](/models/de#de_dep_news_trf) | German | [`bert-base-german-cased`](https://huggingface.co/bert-base-german-cased) | 99.0 | 95.8 | - |
@@ -140,7 +126,7 @@ import Benchmarks from 'usage/\_benchmarks-models.md'
-### New training workflow and config system {#features-training}
+### New training workflow and config system {id="features-training"}
> #### Example
>
@@ -170,7 +156,7 @@ your pipeline. Some settings can also be registered **functions** that you can
swap out and customize, making it easy to implement your own custom models and
architectures.
-
+
@@ -185,7 +171,7 @@ architectures.
-### Custom models using any framework {#features-custom-models}
+### Custom models using any framework {id="features-custom-models"}
> #### Example
>
@@ -210,7 +196,7 @@ follow the same unified [`Model`](https://thinc.ai/docs/api-model) API and each
`Model` can also be used as a sublayer of a larger network, allowing you to
freely combine implementations from different frameworks into a single model.
-
+
@@ -225,11 +211,11 @@ freely combine implementations from different frameworks into a single model.
-### Manage end-to-end workflows with projects {#features-projects}
+### Manage end-to-end workflows with projects {id="features-projects"}
> #### Example
>
-> ```cli
+> ```bash
> # Clone a project template
> $ python -m spacy project clone pipelines/tagger_parser_ud
> $ cd tagger_parser_ud
@@ -246,7 +232,7 @@ project template, adjust it to fit your needs, load in your data, train a
pipeline, export it as a Python package, upload your outputs to a remote storage
and share your results with your team.
-
+
spaCy projects also make it easy to **integrate with other tools** in the data
science and machine learning ecosystem, including [DVC](/usage/projects#dvc) for
@@ -274,11 +260,11 @@ treebank.
-### Parallel and distributed training with Ray {#features-parallel-training}
+### Parallel and distributed training with Ray {id="features-parallel-training"}
> #### Example
>
-> ```cli
+> ```bash
> $ pip install -U %%SPACY_PKG_NAME[ray]%%SPACY_PKG_FLAGS
> # Check that the CLI is registered
> $ python -m spacy ray --help
@@ -295,7 +281,7 @@ the [`ray`](/api/cli#ray) command to your spaCy CLI if it's installed in the
same environment. You can then run [`spacy ray train`](/api/cli#ray-train) for
parallel training.
-
+
@@ -307,7 +293,7 @@ parallel training.
-### New built-in pipeline components {#features-pipeline-components}
+### New built-in pipeline components {id="features-pipeline-components"}
spaCy v3.0 includes several new trainable and rule-based components that you can
add to your pipeline and customize for your use case:
@@ -338,7 +324,7 @@ add to your pipeline and customize for your use case:
-### New and improved pipeline component APIs {#features-components}
+### New and improved pipeline component APIs {id="features-components"}
> #### Example
>
@@ -375,7 +361,7 @@ aren't set.
-### Dependency matching {#features-dep-matcher}
+### Dependency matching {id="features-dep-matcher"}
> #### Example
>
@@ -398,7 +384,7 @@ A pattern added to the dependency matcher consists of a **list of
dictionaries**, with each dictionary describing a **token to match** and its
**relation to an existing token** in the pattern.
-
+
@@ -410,7 +396,7 @@ dictionaries**, with each dictionary describing a **token to match** and its
-### Type hints and type-based data validation {#features-types}
+### Type hints and type-based data validation {id="features-types"}
> #### Example
>
@@ -454,7 +440,7 @@ your config and see validation errors if the argument values don't match.
-### New methods, attributes and commands {#new-methods}
+### New methods, attributes and commands {id="new-methods"}
The following methods, attributes and commands are new in spaCy v3.0.
@@ -484,7 +470,7 @@ The following methods, attributes and commands are new in spaCy v3.0.
| [`project`](/api/cli#project) | Suite of CLI commands for cloning, running and managing [spaCy projects](/usage/projects). |
| [`ray`](/api/cli#ray) | Suite of CLI commands for parallel training with [Ray](https://ray.io/), provided by the [`spacy-ray`](https://github.com/explosion/spacy-ray) extension package. |
-### New and updated documentation {#new-docs}
+### New and updated documentation {id="new-docs"}
@@ -506,7 +492,7 @@ format for documenting argument and return types.
+
+ Get a custom spaCy pipeline, tailor-made for your NLP problem by
+ spaCy's core developers.
+
+
Streamlined. Nobody knows spaCy better than we do. Send
- us your pipeline requirements and we'll be ready to start producing your
- solution in no time at all.
+ us your pipeline requirements and we'll be ready to start producing
+ your solution in no time at all.
Production ready. spaCy pipelines are robust and easy
- to deploy. You'll get a complete spaCy project folder which is ready to{' '}
- spacy project run.
+ to deploy. You'll get a complete spaCy project folder which is
+ ready to spacy project run.
- Predictable. You'll know exactly what you're going to
- get and what it's going to cost. We quote fees up-front, let you try
- before you buy, and don't charge for over-runs at our end — all the risk
- is on us.
+ Predictable. You'll know exactly what you're
+ going to get and what it's going to cost. We quote fees up-front,
+ let you try before you buy, and don't charge for over-runs at our
+ end — all the risk is on us.
- Maintainable. spaCy is an industry standard, and we'll
- deliver your pipeline with full code, data, tests and documentation, so
- your team can retrain, update and extend the solution as your
- requirements change.
+ Maintainable. spaCy is an industry standard, and
+ we'll deliver your pipeline with full code, data, tests and
+ documentation, so your team can retrain, update and extend the solution
+ as your requirements change.
@@ -155,20 +161,21 @@ const Landing = ({ data }) => {
color="#000"
small
>
-
- {/** Update image */}
-
-
-
-
- Prodigy is an annotation tool so efficient that data scientists
- can do the annotation themselves, enabling a new level of rapid iteration.
- Whether you're working on entity recognition, intent detection or image
- classification, Prodigy can help you train and evaluate your
- models faster.
+
+
+
+
+
+
+ Prodigy is an annotation tool so efficient that data
+ scientists can do the annotation themselves, enabling a new level of rapid
+ iteration. Whether you're working on entity recognition, intent
+ detection or image classification, Prodigy can help you{' '}
+ train and evaluate your models faster.
+
- spaCy's new project system gives you a smooth path from prototype to
+ spaCy's new project system gives you a smooth path from prototype to
production. It lets you keep track of all those{' '}
data transformation, preprocessing and{' '}
training steps, so you can make sure your project is always
@@ -236,13 +243,15 @@ const Landing = ({ data }) => {
button="See what's new"
small
>
- spaCy v3.0 features all new transformer-based pipelines that
- bring spaCy's accuracy right up to the current state-of-the-art
- . You can use any pretrained transformer to train your own pipelines, and even
- share one transformer between multiple components with{' '}
- multi-task learning. Training is now fully configurable and
- extensible, and you can define your own custom models using{' '}
- PyTorch, TensorFlow and other frameworks.
+
+ spaCy v3.0 features all new transformer-based pipelines{' '}
+ that bring spaCy's accuracy right up to the current{' '}
+ state-of-the-art. You can use any pretrained transformer to
+ train your own pipelines, and even share one transformer between multiple
+ components with multi-task learning. Training is now fully
+ configurable and extensible, and you can define your own custom models using{' '}
+ PyTorch, TensorFlow and other frameworks.
+
{
color="#252a33"
small
>
-
-
-
-
-
- In this free and interactive online course you’ll learn how to
- use spaCy to build advanced natural language understanding systems, using both
- rule-based and machine learning approaches. It includes{' '}
- 55 exercises featuring videos, slide decks, multiple-choice
- questions and interactive coding practice in the browser.
+
+
+
+
+
+
+ In this free and interactive online course you’ll learn how
+ to use spaCy to build advanced natural language understanding systems, using
+ both rule-based and machine learning approaches. It includes{' '}
+ 55 exercises featuring videos, slide decks, multiple-choice
+ questions and interactive coding practice in the browser.
+
- spaCy v3.0 introduces transformer-based pipelines that bring spaCy's
+ spaCy v3.0 introduces transformer-based pipelines that bring spaCy's
accuracy right up to the current state-of-the-art. You can
also use a CPU-optimized pipeline, which is less accurate but much cheaper
to run.
@@ -285,33 +296,8 @@ const Landing = ({ data }) => {
But
+ Google
+ ORGis starting from behind. The company made a late push into hardware, and
+ Apple
+ ORG’s Siri, available on iPhones, and
+ Amazon
+ ORG’s Alexa software, which runs on its Echo and Dot devices, have clear leads in consumer
+ adoption.
diff --git a/website/public/images/displacy-ent-snek.html b/website/public/images/displacy-ent-snek.html
new file mode 100644
index 000000000..6604d9b78
--- /dev/null
+++ b/website/public/images/displacy-ent-snek.html
@@ -0,0 +1,59 @@
+
diff --git a/website/public/images/displacy-ent1.html b/website/public/images/displacy-ent1.html
new file mode 100644
index 000000000..9fde5cf88
--- /dev/null
+++ b/website/public/images/displacy-ent1.html
@@ -0,0 +1,84 @@
+
+
+ Apple
+ ORG
+
+ is looking at buying
+
+ U.K.
+ GPE
+
+ startup for
+
+ $1 billion
+ MONEY
+
+
diff --git a/website/public/images/displacy-ent2.html b/website/public/images/displacy-ent2.html
new file mode 100644
index 000000000..01ab5c2bf
--- /dev/null
+++ b/website/public/images/displacy-ent2.html
@@ -0,0 +1,86 @@
+
+ When
+
+ Sebastian Thrun
+ PERSON
+
+ started working on self-driving cars at
+
+ Google
+ ORG
+
+ in
+
+ 2007
+ DATE
+
+ , few people outside of the company took him seriously.
+
diff --git a/website/docs/images/displacy-long.html b/website/public/images/displacy-long.html
similarity index 98%
rename from website/docs/images/displacy-long.html
rename to website/public/images/displacy-long.html
index 8938f6a56..e298610aa 100644
--- a/website/docs/images/displacy-long.html
+++ b/website/public/images/displacy-long.html
@@ -5,7 +5,13 @@
class="displacy"
width="1975"
height="399.5"
- style="max-width: none; height: 399.5px; color: #000000; background: #ffffff; font-family: Arial"
+ style="
+ max-width: none;
+ height: 399.5px;
+ color: #000000;
+ background: #ffffff;
+ font-family: Arial;
+ "
>
Apple
diff --git a/website/public/images/displacy-long2.html b/website/public/images/displacy-long2.html
new file mode 100644
index 000000000..c428bd2cb
--- /dev/null
+++ b/website/public/images/displacy-long2.html
@@ -0,0 +1,212 @@
+
diff --git a/website/docs/images/displacy-model-rules.svg b/website/public/images/displacy-model-rules.svg
similarity index 100%
rename from website/docs/images/displacy-model-rules.svg
rename to website/public/images/displacy-model-rules.svg
diff --git a/website/docs/images/displacy-model-rules2.svg b/website/public/images/displacy-model-rules2.svg
similarity index 100%
rename from website/docs/images/displacy-model-rules2.svg
rename to website/public/images/displacy-model-rules2.svg
diff --git a/website/docs/images/displacy-small.svg b/website/public/images/displacy-small.svg
similarity index 100%
rename from website/docs/images/displacy-small.svg
rename to website/public/images/displacy-small.svg
diff --git a/website/public/images/displacy-span-custom.html b/website/public/images/displacy-span-custom.html
new file mode 100644
index 000000000..10cb6dd2d
--- /dev/null
+++ b/website/public/images/displacy-span-custom.html
@@ -0,0 +1,84 @@
+
+ Welcome to the
+
+ Bank
+
+
+
+
+ BANK
+
+
+
+
+ of
+
+
+
+
+ China
+
+
+
+
+ .
+
diff --git a/website/public/images/displacy-span.html b/website/public/images/displacy-span.html
new file mode 100644
index 000000000..cfee1dc7e
--- /dev/null
+++ b/website/public/images/displacy-span.html
@@ -0,0 +1,123 @@
+
+ Welcome to the
+
+ Bank
+
+
+
+
+ ORG
+
+
+
+
+ of
+
+
+
+
+
+ China
+
+
+
+
+
+
+ GPE
+
+
+
+ .
+
diff --git a/website/docs/images/displacy.svg b/website/public/images/displacy.svg
similarity index 100%
rename from website/docs/images/displacy.svg
rename to website/public/images/displacy.svg
diff --git a/website/docs/images/displacy_jupyter.jpg b/website/public/images/displacy_jupyter.jpg
similarity index 100%
rename from website/docs/images/displacy_jupyter.jpg
rename to website/public/images/displacy_jupyter.jpg
diff --git a/website/docs/images/huggingface_hub.jpg b/website/public/images/huggingface_hub.jpg
similarity index 100%
rename from website/docs/images/huggingface_hub.jpg
rename to website/public/images/huggingface_hub.jpg
diff --git a/website/docs/images/lifecycle.svg b/website/public/images/lifecycle.svg
similarity index 100%
rename from website/docs/images/lifecycle.svg
rename to website/public/images/lifecycle.svg
diff --git a/website/docs/images/matcher-demo.jpg b/website/public/images/matcher-demo.jpg
similarity index 100%
rename from website/docs/images/matcher-demo.jpg
rename to website/public/images/matcher-demo.jpg
diff --git a/website/public/images/pipeline-design.svg b/website/public/images/pipeline-design.svg
new file mode 100644
index 000000000..3b528eae5
--- /dev/null
+++ b/website/public/images/pipeline-design.svg
@@ -0,0 +1,56 @@
+
diff --git a/website/docs/images/pipeline.svg b/website/public/images/pipeline.svg
similarity index 100%
rename from website/docs/images/pipeline.svg
rename to website/public/images/pipeline.svg
diff --git a/website/docs/images/pipeline_transformer.svg b/website/public/images/pipeline_transformer.svg
similarity index 100%
rename from website/docs/images/pipeline_transformer.svg
rename to website/public/images/pipeline_transformer.svg
diff --git a/website/docs/images/prodigy.jpg b/website/public/images/prodigy.jpg
similarity index 100%
rename from website/docs/images/prodigy.jpg
rename to website/public/images/prodigy.jpg
diff --git a/website/docs/images/prodigy_overview.jpg b/website/public/images/prodigy_overview.jpg
similarity index 100%
rename from website/docs/images/prodigy_overview.jpg
rename to website/public/images/prodigy_overview.jpg
diff --git a/website/docs/images/prodigy_spans-manual.jpg b/website/public/images/prodigy_spans-manual.jpg
similarity index 100%
rename from website/docs/images/prodigy_spans-manual.jpg
rename to website/public/images/prodigy_spans-manual.jpg
diff --git a/website/docs/images/prodigy_train_curve.jpg b/website/public/images/prodigy_train_curve.jpg
similarity index 100%
rename from website/docs/images/prodigy_train_curve.jpg
rename to website/public/images/prodigy_train_curve.jpg
diff --git a/website/docs/images/project_document.jpg b/website/public/images/project_document.jpg
similarity index 100%
rename from website/docs/images/project_document.jpg
rename to website/public/images/project_document.jpg
diff --git a/website/docs/images/projects.png b/website/public/images/projects.png
similarity index 100%
rename from website/docs/images/projects.png
rename to website/public/images/projects.png
diff --git a/website/docs/images/projects.svg b/website/public/images/projects.svg
similarity index 100%
rename from website/docs/images/projects.svg
rename to website/public/images/projects.svg
diff --git a/website/docs/images/sense2vec.jpg b/website/public/images/sense2vec.jpg
similarity index 100%
rename from website/docs/images/sense2vec.jpg
rename to website/public/images/sense2vec.jpg
diff --git a/website/docs/images/spacy-ray.svg b/website/public/images/spacy-ray.svg
similarity index 100%
rename from website/docs/images/spacy-ray.svg
rename to website/public/images/spacy-ray.svg
diff --git a/website/docs/images/spacy-streamlit.png b/website/public/images/spacy-streamlit.png
similarity index 100%
rename from website/docs/images/spacy-streamlit.png
rename to website/public/images/spacy-streamlit.png
diff --git a/website/docs/images/spacy-tailored-pipelines_wide.png b/website/public/images/spacy-tailored-pipelines_wide.png
similarity index 100%
rename from website/docs/images/spacy-tailored-pipelines_wide.png
rename to website/public/images/spacy-tailored-pipelines_wide.png
diff --git a/website/docs/images/thinc_mypy.jpg b/website/public/images/thinc_mypy.jpg
similarity index 100%
rename from website/docs/images/thinc_mypy.jpg
rename to website/public/images/thinc_mypy.jpg
diff --git a/website/docs/images/tok2vec-listener.svg b/website/public/images/tok2vec-listener.svg
similarity index 100%
rename from website/docs/images/tok2vec-listener.svg
rename to website/public/images/tok2vec-listener.svg
diff --git a/website/docs/images/tok2vec.svg b/website/public/images/tok2vec.svg
similarity index 100%
rename from website/docs/images/tok2vec.svg
rename to website/public/images/tok2vec.svg
diff --git a/website/docs/images/tokenization.svg b/website/public/images/tokenization.svg
similarity index 100%
rename from website/docs/images/tokenization.svg
rename to website/public/images/tokenization.svg
diff --git a/website/docs/images/trainable_component.svg b/website/public/images/trainable_component.svg
similarity index 100%
rename from website/docs/images/trainable_component.svg
rename to website/public/images/trainable_component.svg
diff --git a/website/docs/images/training.svg b/website/public/images/training.svg
similarity index 100%
rename from website/docs/images/training.svg
rename to website/public/images/training.svg
diff --git a/website/docs/images/vocab_stringstore.svg b/website/public/images/vocab_stringstore.svg
similarity index 100%
rename from website/docs/images/vocab_stringstore.svg
rename to website/public/images/vocab_stringstore.svg
diff --git a/website/docs/images/wandb1.jpg b/website/public/images/wandb1.jpg
similarity index 100%
rename from website/docs/images/wandb1.jpg
rename to website/public/images/wandb1.jpg
diff --git a/website/docs/images/wandb2.jpg b/website/public/images/wandb2.jpg
similarity index 100%
rename from website/docs/images/wandb2.jpg
rename to website/public/images/wandb2.jpg
diff --git a/website/public/manifest.webmanifest b/website/public/manifest.webmanifest
new file mode 100644
index 000000000..248d6036c
--- /dev/null
+++ b/website/public/manifest.webmanifest
@@ -0,0 +1,31 @@
+{
+ "theme_color": "#09a3d5",
+ "background_color": "#09a3d5",
+ "display": "minimal-ui",
+ "scope": "/",
+ "start_url": "/",
+ "name": "spaCy",
+ "short_name": "spaCy",
+ "icons": [
+ {
+ "src": "/icons/icon-192x192.png",
+ "sizes": "192x192",
+ "type": "image/png"
+ },
+ {
+ "src": "/icons/icon-256x256.png",
+ "sizes": "256x256",
+ "type": "image/png"
+ },
+ {
+ "src": "/icons/icon-384x384.png",
+ "sizes": "384x384",
+ "type": "image/png"
+ },
+ {
+ "src": "/icons/icon-512x512.png",
+ "sizes": "512x512",
+ "type": "image/png"
+ }
+ ]
+}
diff --git a/website/public/vercel.svg b/website/public/vercel.svg
new file mode 100644
index 000000000..fbf0e25a6
--- /dev/null
+++ b/website/public/vercel.svg
@@ -0,0 +1,4 @@
+
\ No newline at end of file
diff --git a/website/runtime.txt b/website/runtime.txt
index 475ba515c..cc1923a40 100644
--- a/website/runtime.txt
+++ b/website/runtime.txt
@@ -1 +1 @@
-3.7
+3.8
diff --git a/website/setup/jinja_to_js.py b/website/setup/jinja_to_js.py
index e2eca7ffb..3e1963ff7 100644
--- a/website/setup/jinja_to_js.py
+++ b/website/setup/jinja_to_js.py
@@ -206,7 +206,6 @@ class JinjaToJS(object):
self.environment = Environment(
loader=FileSystemLoader(template_root),
autoescape=True,
- extensions=["jinja2.ext.with_", "jinja2.ext.autoescape"],
)
self.output = StringIO()
self.stored_names = set()
diff --git a/website/setup/requirements.txt b/website/setup/requirements.txt
index e7a8e65a7..cbd306cc3 100644
--- a/website/setup/requirements.txt
+++ b/website/setup/requirements.txt
@@ -1,3 +1,3 @@
# These are used to compile the training quickstart config
-jinja2
+jinja2>=3.1.0
srsly
diff --git a/website/setup/setup.sh b/website/setup/setup.sh
index 674b25674..8207c6a5e 100755
--- a/website/setup/setup.sh
+++ b/website/setup/setup.sh
@@ -1 +1 @@
-python jinja_to_js.py ../../spacy/cli/templates/quickstart_training.jinja ../src/widgets/quickstart-training-generator.js ../../spacy/cli/templates/quickstart_training_recommendations.yml
+python setup/jinja_to_js.py ../spacy/cli/templates/quickstart_training.jinja src/widgets/quickstart-training-generator.js ../spacy/cli/templates/quickstart_training_recommendations.yml
diff --git a/website/src/components/accordion.js b/website/src/components/accordion.js
index efe2477a3..504f415a5 100644
--- a/website/src/components/accordion.js
+++ b/website/src/components/accordion.js
@@ -17,7 +17,7 @@ export default function Accordion({ title, id, expanded = false, spaced = false,
[classes.hidden]: isExpanded,
})
// Make sure accordion is expanded if JS is disabled
- useEffect(() => setIsExpanded(expanded), [])
+ useEffect(() => setIsExpanded(expanded), [expanded])
return (