// Define some global attributes
include::_globattr.adoc[]

[[cd_necontexts]]
NE contexts
~~~~~~~~~~~
The context annotator provides a mechanism for examining the context
of existing annotations, finding events of interest in the context,
and acting on those events in some way. The negation and status
annotators both take advantage of this infrastructure by examining the
context of named entities (e.g. disorders and findings) to see if they
should be considered as negated (e.g. ``no chest pain'') or if their
status should be modified (e.g. ``myocardial infarction'' should have
status ``history of'').

In fact, the ``negation annotator'' is really just the context
annotator configured to deal with negations. Similarly, the ``status
annotator'' is the context annotator configured to identify the status
of named entities.

TIP: To better understand the context annotator code you should start
by reading the Javadocs for the class
+edu.mayo.bmi.uima.context.ContextAnnotator.java+. It provides a
conceptual overview of how the code works.


[[negation_annotator]]
Negation annotator
^^^^^^^^^^^^^^^^^^
The negation detection annotator is a pattern-based (no MaxEnt models
required/used) approach that uses finite state machines and is roughly
based on the popular NegEx footnote:[
http://www.dbmi.pitt.edu/chapman/NegEx.html] algorithm introduced by
Wendy Chapman.

What follows is an explanation of how negation is performed using the
context annotator.


NegationAnnotator.xml
+++++++++++++++++++++
We will start by examining the descriptor file
`desc/NegationAnnotator.xml`. It calls
edu.mayo.bmi.uima.context.ContextAnnotator, instead of a
``NegationAnnotator''. In fact, there is no ``negation annotator''
analysis engine -- we simply configure the ContextAnnotator for the
task.

Next we will discuss each of the parameter settings in turn:

- MaxLeftScopeSize = 10
+
The maximum number of annotations that will make up the left-hand side
context is ten. Increase or decrease this parameter setting to
increase or decrease the left hand side context.
+
- MaxRightScopeSize = 10
+
The maximum number of annotations that will make up the right-hand
side context is ten. Increase or decrease this parameter setting to
increase or decrease the right-hand side context.
+
- ScopeOrder = LEFT, RIGHT
+
The context annotator will look for signs of negation on the left-hand
side of a named entity first and then the right-hand side.
+
- ContextAnalyzerClass = edu.mayo.bmi.uima.context.negation.NegationContextAnalyzer
+
The context analyzer looks at the context (e.g. the 10 words on the
left or right of the named entity) and determines if the named entity
should be negated. If it should, then the negation context analyzer
will generate a context hit to be consumed by the context hit consumer
(see <<context_hit_consumer,ContextHitConsumerClass>>.)
+
- [[context_hit_consumer]] ContextHitConsumerClass = edu.mayo.bmi.uima.context.negation.NegationContextHitConsumer
+
The context hit consumer handles context hits generated by the context
analyzer. In this case, the negation context hit consumer simply sets
the certainty of a named entity to -1 which indicates that it has been
negated.
+
- WindowAnnotationClass = edu.mayo.bmi.uima.common.type.Sentence
+
When the context annotator collects the context annotations for a
named entity, it will not look beyond the boundaries of the sentence
that the named entity is found in.
+
- FocusAnnotationClass = edu.mayo.bmi.uima.common.type.NamedEntity
+
The negation annotator is concerned with negating named entities and
thus the focus annotation type (the annotations for which a context is
generated and examined) specifies named entities.
+
- ContextAnnotationClass = edu.mayo.bmi.uima.common.type.BaseToken
+
The context of the named entities is a list of tokens -- this is what
the context analyzer is going to examine.

So, the work of negating a named entity is done by

a. finding negations by the NegationContextAnalyzer
b. updating the status of NamedEntities by the NegationContextHitConsumer.

The former is a pretty lightweight wrapper around another class which
has all of the negation pattern finding logic --
edu.mayo.bmi.fsm.machine.NegationFSM. If you want to update the
pattern matching of negation detection, then you would do it in that
class.

Updating Negex patterns
+++++++++++++++++++++++
Updating the negation detection patterns will involve either

a. trial and error experimentation
b. understanding how the NegationFSM works.

The rules, patterns, words that identify negation are hard-coded into
the class edu.mayo.bmi.fsm.machine.NegationFSM which is found in the
core project. We would suggest starting off with the trial-and-error
approach. For example, if you wanted to add ``impossible'' to the
lexicon of negation words, then you could try adding it to the
_negAdjectivesSet and test the behavior.


Status annotator
^^^^^^^^^^^^^^^^
The way the status annotator works mirrors very closely how the
negation annotator works. You are encouraged to read
<<negation_annotator>>, examine the parameter settings given for
`desc/StatusAnnotator.xml`, and look at
edu.mayo.bmi.fsm.machine.StatusIndicatorFSM.
