+ * This class relies on Apache cTAKES + * that is a natural language processing system for extraction of information + * from electronic medical record clinical free-text. + *
+ * + */ +public class CTAKESContentHandler extends ContentHandlerDecorator { + // Prefix used for metadata including cTAKES annotations + public static String CTAKES_META_PREFIX = "ctakes:"; + + // Configuration object for CTAKESContentHandler + private CTAKESConfig config = null; + + // StringBuilder object used to build the clinical free-text for cTAKES + private StringBuilder sb = null; + + // Metadata object used for cTAKES annotations + private Metadata metadata = null; + + public CTAKESContentHandler(ContentHandler handler, Metadata metadata, CTAKESConfig config) throws MalformedURLException { + super(handler); + this.metadata = metadata; + this.config = config; + this.sb = new StringBuilder(); + } + + public CTAKESContentHandler(ContentHandler handler, Metadata metadata) throws MalformedURLException { + this(handler, metadata, new CTAKESConfig()); + } + + public CTAKESContentHandler() throws MalformedURLException { + this(new DefaultHandler(), new Metadata()); + } + + @Override + public void characters(char[] ch, int start, int length) throws SAXException { + if (config.isText()) { + sb.append(ch, start, length); + } + super.characters(ch, start, length); + } + + @Override + public void endDocument() throws SAXException { + try { + // create an Analysis Engine + AnalysisEngine ae = CTAKESUtils.getAnalysisEngine(config.getAeDescriptorPath(), config.getUMLSUser(), config.getUMLSPass()); + + // create a JCas, given an AE + JCas jcas = CTAKESUtils.getJCas(ae); + + StringBuilder metaText = new StringBuilder(); + for (String name : config.getMetadata()) { + for (String value : metadata.getValues(name)) { + metaText.append(value); + metaText.append(System.lineSeparator()); + } + } + + // analyze text + jcas.setDocumentText(metaText.toString() + sb.toString()); + ae.process(jcas); + + // add annotations to metadata + metadata.add(CTAKES_META_PREFIX + "schema", config.getAnnotationPropsAsString()); + CTAKESAnnotationProperty[] annotationPros = config.getAnnotationProps(); + Collection+ * ... + *
+ * ... + *
+ * CTAKESConfig config = new CTAKESConfig();
+ * parseContext.set(CTAKESConfig.class, config);
+ *
+ * Apache cTAKES is built on top of Apache + * UIMA framework and OpenNLP + * toolkit. + *
+ * + */ +public class CTAKESUtils { + // UIMA Analysis Engine + private static AnalysisEngine ae = null; + + // JCas object for working with the CAS (Common Analysis System) + private static JCas jcas = null; + + // UMLS username property + private final static String CTAKES_UMLS_USER = "ctakes.umlsuser"; + + // UMLS password property + private final static String CTAKES_UMLS_PASS = "ctakes.umlspw"; + + /** + * Returns a new UIMA Analysis Engine (AE). This method ensures that only + * one instance of an AE is created. + * + *+ * An Analysis Engine is a component responsible for analyzing unstructured + * information, discovering and representing semantic content. Unstructured + * information includes, but is not restricted to, text documents. + *
+ * + * @param aeDescriptor + * pathname for XML file including an AnalysisEngineDescription + * that contains all of the information needed to instantiate and + * use an AnalysisEngine. + * @param umlsUser + * UMLS username for NLM database + * @param umlsPass + * UMLS password for NLM database + * @return an Analysis Engine for analyzing unstructured information. + * @throws IOException + * if any I/O error occurs. + * @throws InvalidXMLException + * if the input XML is not valid or does not specify a valid + * ResourceSpecifier. + * @throws ResourceInitializationException + * if a failure occurred during production of the resource. + * @throws URISyntaxException + * if URL of the resource is not formatted strictly according to + * to RFC2396 and cannot be converted to a URI. + */ + public static AnalysisEngine getAnalysisEngine(String aeDescriptor, + String umlsUser, String umlsPass) throws IOException, + InvalidXMLException, ResourceInitializationException, + URISyntaxException { + if (ae == null) { + // UMLS user ID and password. + String aeDescriptorPath = CTAKESUtils.class + .getResource(aeDescriptor).toURI().getPath(); + + // get Resource Specifier from XML + XMLInputSource aeIputSource = new XMLInputSource(aeDescriptorPath); + ResourceSpecifier aeSpecifier = UIMAFramework.getXMLParser() + .parseResourceSpecifier(aeIputSource); + + // UMLS user ID and password + if ((umlsUser != null) && (!umlsUser.isEmpty()) + && (umlsPass != null) && (!umlsPass.isEmpty())) { + /* + * It is highly recommended that you change UMLS credentials in + * the XML configuration file instead of giving user and + * password using CTAKESConfig. + */ + System.setProperty(CTAKES_UMLS_USER, umlsUser); + System.setProperty(CTAKES_UMLS_PASS, umlsPass); + } + + // create AE + ae = UIMAFramework.produceAnalysisEngine(aeSpecifier); + } + return ae; + } + + /** + * Returns a new JCas () appropriate for the given Analysis Engine. This + * method ensures that only one instance of a JCas is created. A Jcas is a + * Java Cover Classes based Object-oriented CAS (Common Analysis System) + * API. + * + *+ * Important: It is highly recommended that you reuse CAS objects rather + * than creating new CAS objects prior to each analysis. This is because CAS + * objects may be expensive to create and may consume a significant amount + * of memory. + *
+ * + * @param ae + * AnalysisEngine used to create an appropriate JCas object. + * @return a JCas object appropriate for the given AnalysisEngine. + * @throws ResourceInitializationException + * if a CAS could not be created because this AnalysisEngine's + * CAS metadata (type system, type priorities, or FS indexes) + * are invalid. + */ + public static JCas getJCas(AnalysisEngine ae) + throws ResourceInitializationException { + if (jcas == null) { + jcas = ae.newJCas(); + } + return jcas; + } + + /** + * Serializes a CAS in the given format. + * + * @param type + * type of cTAKES (UIMA) serializer used to write CAS. + * @param prettyPrint + * {@code true} to do pretty printing of output. + * @param stream + * {@see OutputStream} object used to print out information + * extracted by using cTAKES. + * @throws SAXException + * if there was a SAX exception. + * @throws IOException + * if any I/O error occurs. + */ + public static void serialize(CTAKESSerializer type, boolean prettyPrint, + OutputStream stream) throws SAXException, IOException { + if (type == CTAKESSerializer.XCAS) { + XCASSerializer.serialize(jcas.getCas(), stream, prettyPrint); + } else if (type == CTAKESSerializer.XMI) { + XmiCasSerializer.serialize(jcas.getCas(), jcas.getTypeSystem(), + stream, prettyPrint, new XmiSerializationSharedData()); + } else { + XmlCasSerializer.serialize(jcas.getCas(), jcas.getTypeSystem(), + stream); + } + } + + /** + * Returns the annotation value based on the given annotation type. + * @param annotation {@see IdentifiedAnnotation} object. + * @param property {@see CTAKESAnnotationProperty} enum used to identify the annotation type. + * @return the annotation value. + */ + public static String getAnnotationProperty(IdentifiedAnnotation annotation, + CTAKESAnnotationProperty property) { + String value = null; + if (property == CTAKESAnnotationProperty.BEGIN) { + value = Integer.toString(annotation.getBegin()); + } else if (property == CTAKESAnnotationProperty.END) { + value = Integer.toString(annotation.getEnd()); + } else if (property == CTAKESAnnotationProperty.CONDITIONAL) { + value = Boolean.toString(annotation.getConditional()); + } else if (property == CTAKESAnnotationProperty.CONFIDENCE) { + value = Float.toString(annotation.getConfidence()); + } else if (property == CTAKESAnnotationProperty.DISCOVERY_TECNIQUE) { + value = Integer.toString(annotation.getDiscoveryTechnique()); + } else if (property == CTAKESAnnotationProperty.GENERIC) { + value = Boolean.toString(annotation.getGeneric()); + } else if (property == CTAKESAnnotationProperty.HISTORY_OF) { + value = Integer.toString(annotation.getHistoryOf()); + } else if (property == CTAKESAnnotationProperty.ID) { + value = Integer.toString(annotation.getId()); + } else if (property == CTAKESAnnotationProperty.ONTOLOGY_CONCEPT_ARR) { + FSArray mentions = annotation.getOntologyConceptArr(); + StringBuilder sb = new StringBuilder(); + if (mentions != null) { + for (int i = 0; i < mentions.size(); i++) { + if (mentions.get(i) instanceof UmlsConcept) { + UmlsConcept concept = (UmlsConcept) mentions.get(i); + sb.append(concept.getCui()); + if (i < mentions.size()-1) { + sb.append(","); + } + } + } + } + value = sb.toString(); + } else if (property == CTAKESAnnotationProperty.POLARITY) { + value = Integer.toString(annotation.getPolarity()); + } + return value; + } + + /** + * Resets cTAKES objects, if created. This method ensures that new cTAKES + * objects (a.k.a., Analysis Engine and JCas) will be created if getters of + * this class are called. + */ + public static void reset() { + // Analysis Engine + ae.destroy(); + ae = null; + + // JCas + jcas.reset(); + jcas = null; + } +}