replaCy: match & replace with spaCy

We found that in multiple projects we had duplicate code for using spaCy’s blazing fast matcher to do the same thing: Match-Replace-Grammaticalize. So we wrote replaCy!

Match - spaCy’s matcher is great, and lets you match on text, shape, POS, dependency parse, and other features. We extended this with “match hooks”, predicates that get used in the callback function to further refine a match.
Replace - Not built into spaCy’s matcher syntax, but easily added. You often want to replace a matched word with some other term.
Grammaticalize - If you match on ”LEMMA”: “dance”, and replace with suggestions: ["sing"], but the actual match is danced, you need to conjugate “sing” appropriately. This is the “killer feature” of replaCy

Requirements

spacy >= 2.0 (not installed by default, but replaCy needs to be instantiated with an nlp object)

Installation

pip install replacy

Quick start

from replacy import ReplaceMatcher
from replacy.db import load_json
import spacy


match_dict = load_json('/path/to/your/match/dict.json')
# load nlp spacy model of your choice
nlp = spacy.load("en_core_web_sm")

rmatcher = ReplaceMatcher(nlp, match_dict=match_dict)

# get inflected suggestions
# look up the first suggestion
span = rmatcher("She extracts revenge.")[0]
span._.suggestions
# >>> ['exacts']

Input

ReplaceMatcher accepts both text and spaCy doc.

# text is ok
span = r_matcher("She extracts revenge.")[0]

# doc is ok too
doc = nlp("She extracts revenge.")
span = r_matcher(doc)[0]

match_dict.json format

Here is a minimal match_dict.json:

{
  "extract-revenge": {
    "patterns": [
      {
        "LEMMA": "extract",
        "TEMPLATE_ID": 1
      }
    ],
    "suggestions": [
      [
        {
          "TEXT": "exact",
          "FROM_TEMPLATE_ID": 1
        }
      ]
    ],
    "match_hook": [
      {
        "name": "succeeded_by_phrase",
        "args": "revenge",
        "match_if_predicate_is": true
      }
    ],
    "test": {
      "positive": [
        "And at the same time extract revenge on those he so despises?",
        "Watch as Tampa Bay extracts revenge against his former Los Angeles Rams team."
      ],
      "negative": ["Mother flavours her custards with lemon extract."]
    }
  }
}

For more information how to compose match_dict see our wiki:

Citing

If you use replaCy in your research, please cite with the following BibText

@misc{havens2019replacy,
    title  = {SpaCy match and replace, maintaining conjugation},
    author = {Sam Havens, Aneta Stal, and Manhal Daaboul},
    url    = {https://github.com/Qordobacode/replaCy},
    year   = {2019}
}

Metadata

Release files for replacy 3.7.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for replacy 3.7.2
File	Size	Uploaded
replacy-3.7.2.tar.gz	27.4 kB	Oct 31, 2022	Details

Built distribution (wheel)

Table of built distributions (wheels) for replacy 3.7.2
File	Interpreter	ABI	Platform	Reset
replacy-3.7.2-py3-none-any.whl 30.1 kB Oct 31, 2022	Python 3	none	any	Details

Total release size: 57.5 kB

Release files / replacy-3.7.2.tar.gz

Download URL	replacy-3.7.2.tar.gz
Size	27.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`218d4314a434fad6f2e275bc83ca6422a281b44ab6ea480ed81c4b33febe2271`
BLAKE2b-256 checksum How to use checksums	`b23a652fc5853e6e14d6dc7433ec9643bc327d82c9e277b1297380544a68f72a`
Upload date	Oct 31, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/1.1.11 CPython/3.8.13 Linux/5.15.0-1021-gcp`

Release files / replacy-3.7.2-py3-none-any.whl

Download URL	replacy-3.7.2-py3-none-any.whl
Size	30.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`be52d3d4990fcd609428c8ddcbc7a8698d2484dc97edc23d67329167c019e912`
BLAKE2b-256 checksum How to use checksums	`0e11d1290d3e53f044f38113a0987bb4e7df1b288e0c9c0b911fe84b241fde19`
Upload date	Oct 31, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/1.1.11 CPython/3.8.13 Linux/5.15.0-1021-gcp`