Clinical basicsOne synthetic note, start to finish

What cTAKES is doing to the note

cTAKES does not read a chart the way a clinician does. It marks exact character spans, attaches terminology candidates and model attributes, and leaves those rows for review or downstream analysis.

Input: One UTF-8 clinical note
Core action: Span annotation
Terminology: UMLS 2026AA
Medication codes: RxNorm
Canonical result: SQLite schema 6
Clinical meaning: Candidate, not diagnosis

Start with the exact words in the note

The wrapper keeps the original text. cTAKES then records where a phrase begins and ends. Those numbers are offsets, which means another person can return to the same characters and see what produced the row.

Synthetic note

USDHUB00000000000000000001.SYNTHETIC-DEMO.txt

ConceptNegatedMedication

SYNTHETIC NOTE - no patient data.

Assessment
started yesterday. No .

Plan
Start 10 mg by mouth twice daily for 5 days.

Imaging context
A near the right kidney is described.

Select a phrase. The matching row below carries the same source evidence.

Span	What cTAKES adds	What it does not establish
46-62	A concept candidate, semantic type, assertion fields, and a possible right-flank location relation.	That the patient has a confirmed diagnosis.
85-90	A concept candidate with polarity `NEG` because the note says “No fever.”	That every blank polarity elsewhere means positive.
104-111	A medication candidate plus literal dose, route, frequency, duration, and status evidence.	That the drug was dispensed, administered, taken, or reconciled.
170-174	Two retained terminology candidates and, only when every WSD requirement passes, one `Y` and one `N`.	That either candidate is a clinically confirmed finding.

A note phrase becomes a bounded text span, then a terminology candidate row, and finally a row that still requires clinical interpretation. — Figure 1. The row stays connected to the phrase that created it. Clinical review happens after extraction, not inside the terminology lookup.

Terminologies and ontologies give different wording shared candidate identifiers

A terminology is a maintained set of coded clinical concepts and names. An ontology also records formal relationships among concepts. UMLS integrates many source vocabularies and can link synonymous or aligned source concepts under a CUI, so phrases such as “renal calculus” and “kidney stone” can return a shared candidate identity even though the wording differs.

The mapping does not decide whether the concept is true for this patient or guarantee that one CUI perfectly captures the sentence. Assertion models and the source sentence carry separate information such as negation or uncertainty.

Clinical phrases are looked up in a versioned dictionary and mapped to CUI or RxCUI candidates while the original words remain attached to the row. — Figure 2. The dictionary is the local lookup built from the terminology release. The ontology is the concept system those identifiers come from.

Four identifiers clinicians will see

Field	Plain meaning	Example use
`CUI`	A UMLS Concept Unique Identifier. It links synonymous terms to one concept identity.	Compare concept counts across sites without relying on the exact note wording.
`RxCUI`	An RxNorm concept identifier attached to a medication candidate.	Keep the coded medication identity with the same CUI/RxCUI row.
`TUI`	A UMLS semantic-type identifier.	Distinguish a disease/disorder type from an anatomy or drug type.
Preferred term	The dictionary’s selected human-readable label for that candidate.	Display the terminology label beside the original note phrase.

A cTAKES recipe is the ordered list of stages that touch the note

The recipe is a small .piper file. It tells cTAKES which analysis engines to load and in what order. Changing that order can change the output because one stage often needs annotations created by an earlier stage.

The reviewed recipe runs sectioning and tokenization, dictionary lookup, candidate-preserving WSD, Drug NER, assertion models, relation models, and then the requested writers. — Figure 3. The internal recipe key is `star`. That technical key is retained for compatibility; USDHUB is the public workflow and filename identity.

Stage	What it adds	Why order matters
Sections, sentences, tokens, POS, chunks	Text structure and bounded spans.	Dictionary and model annotations need the token and sentence boundaries.
Dictionary lookup	CUI, RxCUI, TUI, preferred-term candidates.	WSD can only compare candidates that lookup already created.
Graph/context WSD	A winner/loser marker only when profiles, direct evidence, raw score, and margin all pass; otherwise blanks.	It groups same-span candidates before writers serialize them.
Drug NER	Medication mentions and dose/route/frequency/date attributes.	It runs before assertions so medication mentions can receive assertion fields.
Assertions	Polarity, uncertainty, conditional, generic, and subject.	The workbook requests these five fields, so the matching Apache models are loaded.
Relations	Degree and anatomic-location links.	The writer can remove self-links and select a deterministic supported relation.
CAS writers	Canonical SQLite and optional native XMI.	The note and its rows commit together before post-run checks begin. CSV is exported from completed SQLite afterward.

Read the mechanism: pipelines/production/star.piper defines the reviewed stage order, and tools/reporting/uima/AnnotationSqliteWriter.java writes the canonical rows.

Assertions describe how the note talks about a candidate

A CUI alone says which concept matched. Assertion fields say whether the language is negated, uncertain, conditional, generic, or about someone other than the patient. The wrapper keeps missing values blank because a fabricated default would look like a model result.

Source wording	Candidate	Assertion interpretation
“No fever”	Fever candidate remains	Polarity is negative. The row is retained so the absence is represented rather than erased.
“Possible obstruction”	Obstruction candidate remains	Uncertainty may be populated by the Apache assertion model.
“Mother had stones”	Stone candidate may remain	Subject can distinguish family context when the model supports it; blank remains blank when it does not.

Degree and location relations are separate. A pain candidate can link to a right-flank anatomy candidate, while a severity cue can link to the concept it modifies. These links still need representative clinical review because a structurally valid relation can point in the wrong direction or attach to the wrong nearby site.

WSD handles one phrase with more than one terminology candidate

Word-sense disambiguation is needed when the same text span has multiple distinct CUIs. The wrapper’s WSD reads the bounded sentence context, dictionary terms, definitions, semantic types, and a small terminology-relation neighborhood. It keeps every candidate row. A decision requires a model profile for every candidate, direct lexical, graph, or preferred-term evidence for the leading candidate, a sufficient raw score, and a sufficient normalized margin.

Synthetic span: “mass” with context “near the right kidney”

Compare a decision with an abstention

Body-structure0.682WSD = Y

Quantitative0.318WSD = N

Both rows remain. Complete profiles, direct evidence, score, and margin allow Y and N to be written.

With WSD disabled, both candidate rows remain and both WSD columns are blank. With WSD enabled, both rows still remain. The only change is that a passing ambiguity group receives one Y, one or more N values, and normalized within-mention scores. An abstention leaves the WSD columns blank.

Read the full WSD method, thresholds, default behavior, validation, and startup correction. The wrapper-owned implementation is visible in tools/wsd/GraphContextWsdAnnotator.java.

Federated learning keeps the source notes at each site

In a federated study, Site A and Site B do not pool their raw notes into one central folder. Each site runs the same extraction definition locally. The study protocol then decides whether approved features, counts, model updates, or aggregates may leave the site.

The wrapper supports the first requirement: both sites can prove they used the same wrapper source, pipeline, dictionary bytes, SQLite schema, and WSD model by comparing analysis_id. It does not implement the federated trainer, authentication, secure aggregation, coordinator, or privacy accounting.

Two sites keep notes, SQLite, XMI, and the clinician viewer local, run the same analysis identity, and release only protocol-approved features or aggregates. — Figure 4. Matching extraction is a prerequisite for comparison. It is not the complete federated-learning system.

Read the full multi-site workflow and data boundary.

Short glossary

Term	Meaning in this wrapper
Annotation	A span of source text plus fields cTAKES attached to that span.
UMLS	The Unified Medical Language System. It connects many source terminologies under shared identifiers and semantic types; the local release here is 2026AA.
RxNorm	A standardized medication terminology. An RxCUI identifies a drug concept such as an ingredient or brand candidate.
SNOMED CT	A broad clinical terminology used here as one source of findings, disorders, anatomy, procedures, and other clinical concepts.
LOINC	A terminology for laboratory tests, clinical measurements, and related observations. Its UMLS source abbreviation is `LNC`.
CAS / XMI	The native cTAKES analysis object, and its XML serialization. It contains the full note and many intermediate annotations.
Candidate	A supported terminology or medication match emitted by cTAKES. It is not automatically an adjudicated clinical fact.
Dictionary	The local database cTAKES queries to turn note phrases into terminology candidates.
Ontology	The maintained concept system that gives clinical meanings stable identifiers and relationships.
NER	Named-entity recognition: finding bounded mentions such as medications in source text and attaching structured fields.
POS	Part of speech, such as noun or verb, assigned to a token and retained as syntax evidence.
UIMA	The framework cTAKES uses to pass one analysis object through an ordered set of engines.
UTF-16 offset	A begin or end position counted the way Java indexes text. The stored offset lets the reviewer recover the exact source characters, including text outside basic ASCII.
Relation	A directed link between annotations, such as a finding linked to an anatomic location or degree indicator.
Piper / recipe	The ordered cTAKES stage definition used for the run.
Assertion	Model output such as polarity, uncertainty, conditional, generic, or subject.
WSD	Candidate-preserving word-sense disambiguation for same-span ambiguity groups.
SQLite	The canonical relational database that stores exact source notes, rows, and run identities before the CSVs are exported.
`analysis_id`	A content-derived identity for the extraction definition: wrapper source, effective recipe, dictionary database, schema, and WSD state/model.
`run_id`	A new audit identity for one execution. Two runs can share an analysis ID and still have different run IDs.
Receipt	A JSON or manifest file recording what was checked, which bytes ran, and whether the batch completed.

Continue to the exact terminology selection, or see how these terms and identities appear in the delivered files.