How patrickthealba/prostate-cancer-phenotyping works
Project type and purpose
• This is a specialized NLP pipeline tool for extracting metastatic prostate cancer and castration-resistant prostate cancer diagnoses from clinical text.
• It builds on the Leo framework (a UIMA AS–based NLP pipeline) and provides configurable readers and listeners to integrate with file systems or databases.
File structure
• Top-level directories:
• config/ – Groovy configuration for the UIMA AS client, service, readers, listeners, and annotator descriptors.
• data/input/ – Sample text input files.
• generated-types/ – Auto-generated Java and XML type system definitions for all annotation types.
• src/main/java/ – Core Java code: LeoClient, LeoServiceMetastasis, pipeline definitions, annotator implementations, listener logic.
• src/main/java/resources/ – Pattern, rule, and stopword files used by regex and pattern annotators.
• lib/, pom.xml – Maven build and external dependencies (Leo, UIMA AS).
Key insights from the README
• The entry point is a UIMA AS service (“LeoServiceMetastasis”) invoked by a client (“LeoClient”).
• Readers (file or database) submit CASes to the UIMA AS broker; the service picks up CASes, runs the Metastasis_Pipeline, then dispatches results to configured listeners (XMI file writer, CSV writer, database writer).
• The pipeline is a linear sequence of annotators: Regex → Merge → Pattern → AnchoredSentence → Context → MetastasisLogic.
Main components
a. Input layer (Collection Readers)
• FileCollectionReaderConfig
• DatabaseCollectionReaderConfig / BatchDatabaseCollectionReaderConfig
b. UIMA AS infrastructure
• UIMA AS Broker (message queue)
• LeoClient (pushes CAS to broker)
• LeoServiceMetastasis (pulls CAS from broker, runs pipeline)
c. NLP Pipeline (Metastasis_Pipeline)
1. RegexAnnotator (Metastasis terms, exclude terms)
2. MergeAnnotator (overlap resolution)
3. AnnotationPatternAnnotator (hormone, medication, other patterns)
4. AnchoredSentenceAnnotator (context window creation)
5. ContextAnnotator (negation, experiencer, temporality)
6. MetastasisLogic (final mPCa_flag, castrate_resistant output types)
d. Type System & generated-types
• TypeSystem.java + generated-types/classes and resources (TypeSystem.xml)
e. Output layer (Listeners)
• SimpleXmiListenerConfig → writes XMI files
• CsvListenerConfig → writes CSV
• MetastasisDatabaseListenerConfig → writes back to database
Relationships and data flow
• Readers → (CAS) → UIMA AS Broker → LeoServiceMetastasis → (invokes) Metastasis_Pipeline → (enriched CAS) → Listeners → output sinks (filesystem, DB).
• LeoClient is an alternate front end that can submit CAS to the broker programmatically.
• Configuration files (Groovy) parameterize readers, listeners, and service settings (host, port).
• The pipeline reads resource patterns and rules from src/main/java/resources at runtime.
Architectural patterns and principles
• Pipeline pattern (linear chain of annotators operating on a shared CAS).
• Configuration-driven design (readers/listeners/annotators wired via Groovy scripts).
• Separation of concerns:
• Readers handle input retrieval
• Annotators perform text analysis
• Listeners handle output persistence
• Type system defines shared data schema
• Extensibility points: add new annotators, readers, or listeners by implementing UIMA components and updating configs.