displaCy ENT: A modern named entity visualiser

Data exploration is an important part of effective named entity recognition because systems often make common unexpected errors that are easily fixed once identified. Despite the apparent simplicity of the task, automatic named entity recognition systems still make many errors, unless trained on examples closely tailored to the use-case. Check out the demo to visualise spaCy's guess at the named entities in the document. You can filter the displayed types, to only show the annotations you're interested in.

To read more about displaCy-ent.js, check out the blog post.

displaCy-ent.js written in ECMAScript 6. For full, cross-browser compatibility, make sure to use a compiler like Babel. For more info, see this compatibility table.

Using displacy-ent.js

To use displaCy ENT in your project, include displacy-ent.js from GitHub or via npm:

npm install displacy-ent

Then initialize a new instance specifying the API and settings:

const displacy = new displaCyENT('http://localhost:8000', {
    container: '#displacy',
    defaultText: 'When Sebastian Thrun started working on self-driving cars at Google in 2007, few people outside of the company took him seriously.',
    defaultEnts: ['person', 'org', 'date']
});

Our service that produces the input data is open source, too. You can find it at spacy-services.

The following settings are available:

| Setting | Description | Default | | --- | --- | --- | | container | element to display text in, can be any query selector | #displacy | | defaultText | text used if displaCy ENT is run without text specified | 'When Sebastian Thrun started working on self-driving cars at Google in 2007, few people outside of the company took him seriously.' | | defaultModel | model used if displaCy ENT is run without model specified | 'en' | | defaultEnts | array of entities highlighted in text | ['person', 'org', 'gpe', 'loc', 'product'] | | onStart | function to be executed on start of server request | false | | onSuccess | callback function to be executed on successful server response | false | | onRender | callback function to be executed when visualisation has rendered | false | | onError | function to be executed if request fails | false |

Visualising Entities

The parse(text, model, ents) method renders a text for a given set of entities in the container.

const text = 'When Sebastian Thrun started working on self-driving cars at Google in 2007, few people outside of the company took him seriously.';
const model = 'en';
const ents = ['person', 'org', 'date'];

displacy.parse(text, model, ents);

Rendering Entities Manually

Alternatively, you can use render() to manually render a text and its entity spans for a given set of entities:

const text = 'When Sebastian Thrun started working on self-driving cars at Google in 2007, few people outside of the company took him seriously.';
const spans = [ { end: 20, start: 5, type: "PERSON" }, { end: 67, start: 61, type: "ORG" }, { end: 75, start: 71, type: "DATE" } ];
const ents = ['person', 'org', 'gpe', 'loc', 'product'];

displacy.render(text, spans, ents);

How it works

displaCy ENT uses only the <mark> element with data attributes and custom CSS styling. No additional, visible content or markup is added to your input text and no JavaScript is required to display the entities.

Here's an example of the markup:

<div class="entities">
    When <mark data-entity="person">Sebastian Thrun</mark> started working on self-driving cars at
    <mark data-entity="org">Google</mark> in <mark data-entity="date">2007</mark>, few people outside of the
    company took him seriously.
</div>

And here is the CSS it needs to display the entity labels:

.entities {
    line-height: 2;
}

[data-entity] {
    padding: 0.25em 0.35em;
     margin: 0px 0.25em;
     line-height: 1;
     display: inline-block;
     border-radius: 0.25em;
     border: 1px solid;
}

[data-entity]::after {
    box-sizing: border-box;
    content: attr(data-entity);
    font-size: 0.6em;
    line-height: 1;
    padding: 0.35em;
    border-radius: 0.35em;
    text-transform: uppercase;
    display: inline-block;
    vertical-align: middle;
    margin: 0px 0px 0.1rem 0.5rem;
}

[data-entity][data-entity="person"] {
    background: rgba(166, 226, 45, 0.2);
    border-color: rgb(166, 226, 45);
}

[data-entity][data-entity="person"]::after {
    background: rgb(166, 226, 45);
}

[data-entity][data-entity="org"] {
    background: rgba(67, 198, 252, 0.2);
    border-color: rgb(67, 198, 252);
}

[data-entity][data-entity="org"]::after {
    background: rgb(67, 198, 252);
}

[data-entity][data-entity="date"] {
    background: rgba(47, 187, 171, 0.2);
    border-color: rgb(47, 187, 171);
}

[data-entity][data-entity="date"]::after {
    background: rgb(47, 187, 171);
}

Entity labels are taken from the data-entity attribute and are rendered after the span as a CSS pseudo element.