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

[[cd_drugner]]
=== Drug NER (optional) ===
The Drug NER (Drug Named Entity Recognition, also referred to as Medication Annotator) processes flat files or CDA (plain text wrapped with Clinical Document Architecture) documents to identify drug NEs and related attributes such as dosage, strength, route, etc. The annotator extracts data from both lists as well as narrative text.

[NOTE]
//.Disclaimer
====
See <<binary_install>>, <<compile_from_source>>, or <<compile_in_eclipse>> for
detailed install and setup information pertaining to all the
{osp-short} components.  Other `optional' components need not be installed for Drug NER to work.
For additional documentation pertaining to this pipeline see
//+{inst-root-dir}/Drug NER/doc/drugner.pdf+ and
+{inst-root-dir}/Drug NER/README+.
====

Analysis engines (annotators)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- *DrugAggregateCDAProcessor.xml*
+
--
The file +desc/analysis_engine/DrugAggregateCDAProcessor.xml+ provides
a working example of the Medication Annotator. This aggregate includes
DrugLookupWindow, DrugMention Annotator and various annotators form
{osp-short} release all of whom can be found in projects at
*{inst-root-dir}/*.

- DrugMentionAnnotator
- DrugLookupWindowAnnotator

[NOTE]
=======================================================================
+DrugAggregateCDAProcessor.xml+ is also provided to process CDA documents. The aggregate flow will contain the annotator version CdaCasInitializer.xml which will process the document as a Clinic Document Architecture (CDA) wrapped file. Additionally, the Sofa Mappings are enabled for the 'plaintext' output view, which is intented to handle mapping the DTD properties to properties used by the pipeline (e.g. Patient and date meta-data).
=======================================================================
//--
//+
//- *CdaCasInitializer.xml*
//+
//--
//This annotator is referenced from +{inst-root-dir}/document preprocessor/desc/+.
// and the documentation for this can also be found +{inst-root-dir}/document preprocessor/+.
//--
//+
//- *SentenceDetectorAnnotator.xml*
//+
//--
//This annotator is referenced from +{inst-root-dir}/core/desc/+.
// and the documentation for this can also be found +{inst-root-dir}/core/+.
//--
//+
//- *TokenizerAnnotator.xml*
//+
//--
//This annotator is referenced from +{inst-root-dir}/core/desc/+.
// and the documentation for this can also be found +{inst-root-dir}/core/+.
//--
//+
//- *LvgAnnotator.xml*
//+
//--
//This annotator is referenced from +{inst-root-dir}/LVG/desc/+.
// and the documentation for this can also be found +{inst-root-dir}/LVG/+.
//--
//+
//- *ContextDependentTokenizerAnnotator.xml*
//+
//--
//This annotator is referenced from +{inst-root-dir}/context depedent tokenizer/desc/+.
// and the documentation for this can also be found +{inst-root-dir}/context depedent tokenizer/+.
//--
//+
//- *POSTagger.xml*
//+
//--
//This annotator is referenced from +{inst-root-dir}/POS tagger/desc/+.
// and the documentation for this can also be found +{inst-root-dir}/POS tagger/+.
//--
//+
//- *Chunker.xml*
//+
//--
//This annotator is referenced from +{inst-root-dir}/chunker/desc/+.
// and the documentation for this can also be found +{inst-root-dir}/chunker/+.
--
+
- *DrugLookupWindowAnnotator.xml*
+
--
This annotator is referenced from +{inst-root-dir}/clinical documents pipeline/desc/+ with customizations. The original LookupWindowAnnotator is an Aggregate which includes NP2LookupWindow and MaxLookupWindows annotators. DrugLookupWindow aggregate adds DrugCNP2LookupWindow annotator to the original set of annotators in the flow.

*Parameters*::
 srcDrugObjClass <String/Single-valued/Required>;;  ([brown]#Default Value# = `edu.mayo.bmi.uima.chunker.type.NP')
Identifies the Chunk type that needs to be used to generate DrugLookupWindowAnnotation. 
 destDrugObjClass <String/Single-valued/Required>;;  ([brown]#Default Value# = `edu.mayo.bmi.uima.lookup.type.DrugLookupWindowAnnotation')
Identifies the destination type that the Chunk type defined by srcDrugObjClass is the source of. 
 dataDrugBindMap <String/Multi-valued/Required>;;  ([brown]#Default Values# = `getBegin|setBegin, getEnd|setEnd')
Binds data from source to destination.
 sectionOverrideSet <String/Multi-valued/Optional>;;  ([brown]#Default Values# = `getBegin|setBegin, getEnd|setEnd')
Identifies the sections which as a whole should be treated as a lookup window.
--
+
- *DrugCNP2LookupWindow.xml*
+ 
--
This annotator generates new DrugLookupWindow annotations for the sections whose seaction ids are specified in the parameter - sectionOverrideSet. The default for out of the box configuration does not contain any section ids specified. Please read +{inst-root-dir}/drugner/README+ for more information on recommended usage.
--
+
- *DictionaryLookupAnnotator.xml*
+
--
This annotator is referenced from +{inst-root-dir}/chunker/desc/+ and the documentation for this can also be found +{inst-root-dir}/chunker/+.
--
+
- *DrugMentionAnnotator.xml*
+
--
This annotator adds the ability to identify attributes of  drug mentions such as Dosage, Frequency, Frequency Unit, Route and Strength from either plaintext or CDA documents. It also provides the ability to specify which sections of a note contain drugs in a list format versus drug mentions within the narrative of the note. This allows for customized processing done on different sections and generally improves the quality of the annotations.  This project utilizes various {osp-short} components and hence requires {osp-short} to be installed prior to using this component.

*Parameters*::
 medicationRelatedSection <String/Single-valued/Optional>;; ([brown]#Defaule Value# = `SIMPLE_SEGMENT')
IDs of sections generated by your Segment Annotator where drug mentions appear in a list format.
--
+
- *StatusAnnotator.xml*
+
--
This annotator is referenced from +{inst-root-dir}/NE contexts/desc+. The original documentation for StatusAnnotator can also be found in +{inst-root-dir}/NE contexts/+ where one can read more about the usage information and configuration details.
--
+
- *NegationAnnotator.xml*
+
--
This annotator is referenced from +{inst-root-dir}/NE contexts/desc+. The original documentation for NegationAnnotator can also be found in +{inst-root-dir}/NE contexts/+ where one can read more about the usage information and configuration details.
--
+
- *DrugNER_PlainText_CPE.xml*
+
--
The file +desc/DrugNER_PlainText_CPE.xml+ provides an XML-specification of a
collection processing engine (CPE). To run the CPE:

. Start UIMA CPE GUI.
+
___________________________________________________________
+*java -cp {osp-cp} org.apache.uima.tools.cpm.CpmFrame*+
___________________________________________________________
+
. Open this file.
. Set the parameters for the collection reader to point to a local
  collection of files that you want part-of-speech tagged.
. Set the parameters for the DrugMentionAnnotator as appropriate for your
  environment.
. Set the output directory of the XCAS Writer CAS Consumer.

The results of running the pipeline are written to the output
directory as XCAS files. These files can be viewed in the CAS Visual
Debugger.

A sample plian text document has been provided for convenience that can be used 
as input document for the process described above.

[NOTE]
============================================================
The steps described under +DrugNER_PlainText_CPE.xml+ can be used to process the 
sample document provided to validate Drug NER pipeline.
============================================================
--

