negspacy

The termset module provides functionality for managing negation patterns. Note the following technical details:

• Class Naming: The class is named termset (lowercase). While this deviates from PEP 8, it is preserved for backward compatibility. Users should treat it as a standard class.
• Pattern Management: The API includes methods for add_patterns and remove_patterns to manage the underlying termsets.
• Error Handling: Attempting to use an invalid neg_termset will raise a KeyError.

When using negspacy with spaCy 3.8+, be aware of the following API details:

• NegEx Factory: The @Language.factory("negex", default_config=...) pattern remains unchanged and is the standard way to add the component to a pipeline.
• Span Extensions: Span.set_extension(name, default=False, force=True) is used to attach negation attributes to spans.
• PhraseMatcher: The 2-argument form of PhraseMatcher.add("name", patterns) is deprecated. It is recommended to use the 3-argument form or pass patterns as a list to avoid UserWarning.
• SpanGroups: Accessing spans via doc.spans[key] is compatible with spaCy 3.x and creates a SpanGroup.

Some NER models (like en_core_sci_sm) might include negation words within the entity span itself (e.g., "no headache" as a single entity). This prevents the NegEx algorithm from seeing the negation as a separate preceding word.

To fix this, use the chunk_prefix configuration key to tell negex which words to treat as part of the negation context even if they are part of a chunk.

from negspacy.termsets import termset

nlp = spacy.load("en_core_sci_sm")
ts = termset("en_clinical")

# Add negex with chunk_prefix to catch 'no' in 'no headache'
nlp.add_pipe(
    "negex",
    config={
        "chunk_prefix": ["no"],
    },
    last=True,
)

doc = nlp("There is no headache.")
for e in doc.ents:
    print(e.text, e._.negex)
# Output: no headache True

Install negspacy via pip. To use it, load a spaCy language model and add the negex pipeline component. You can optionally filter negation detection to specific entity types using the ent_types configuration key.

pip install negspacy

import spacy
from negspacy.negation import Negex

# Load model and add negex component
nlp = spacy.load("en_core_web_sm")
nlp.add_pipe("negex", config={"ent_types":["PERSON","ORG"]})

# Process text
doc = nlp("She does not like Steve Jobs but likes Apple products.")

# Access negation status via the ._.negex attribute
for e in doc.ents:
    print(e.text, e._.negex)

NegEx uses termsets to identify negation patterns. The default termset is en_clinical. You can choose different termsets using the termset function:

• en: General English phrases.
• en_clinical (Default): General English plus clinical domain phrases.
• en_clinical_sensitive: Adds phrases to help rule out historical or irrelevant entities.

To use a specific termset, pass its patterns to the neg_termset config key when adding the pipeline.

from negspacy.negation import Negex
from negspacy.termsets import termset

# Create a termset
ts = termset("en")

nlp = spacy.load("en_core_web_sm")
nlp.add_pipe(
    "negex",
    config={
        "neg_termset": ts.get_patterns()
    }
)

If your spaCy pipeline uses a Span Categorizer that adds spans to the Doc object, you can instruct negex to detect negations for those spans by providing a list of keys to the span_keys argument in the configuration.

# Assuming 'sc' is the SpanGroup key added by your model
nlp = spacy.load("your_span_cat_model")
nlp.add_pipe("negex", config={"span_keys":["sc"]})

doc = nlp("Analysis showed no sign of Human TR Beta 1 mRNA")

for span in doc.spans["sc"]:
    print(span.text, span.label, span._.negex)

When adding the negex component via nlp.add_pipe("negex", config={...}), you can use the following keys to control the negation logic:

As part of the modernization plan, negspacy targets Python 3.9 or higher. The core dependency is spacy, specifically requiring versions >=3.8 and <4.0. For development purposes, the following optional dependencies are used:

• pytest>=8
• pytest-cov
• ruff
• pre-commit

dependencies = ["spacy>=3.8,<4.0"]

[project.optional-dependencies]
dev = ["pytest>=8", "pytest-cov", "ruff", "pre-commit"]

Once the negex component has processed a Doc, it attaches a boolean attribute to the spans (entities or chunks) it identifies as negated.

By default, this attribute is accessed via ._.negex. If you configured a different extension_name during pipeline setup, use that name instead.

Example:

# If extension_name was 'negex'
if span._.negex:
    print("This entity is negated")