Run cTAKES from the terminal interface

Install and run the known-answer test

Paste this complete line into Linux or WSL. The main branch keeps the command current; setup downloads the release-matched immutable assets, verifies their checksums, chooses the newest supported Python already on the machine, and creates a private virtual environment. It does not replace the system Python.

git clone --branch main --depth 1 https://codeberg.org/editnori/Ctakes_USD.git Ctakes_USD && cd Ctakes_USD && bash scripts/setup.sh --tui && ./ctakes verify && ./ctakes tui

After installation, reopen the interface from any folder with ctakes tui. If the shell has not refreshed its PATH, enter the repository and use ./ctakes tui.

Confirm the home screen says ready

The green ready banner means setup, system diagnostics, and the included sample test have passed. If the screen instead offers Run sample test, run it before selecting clinical notes. Then choose New run.

Choose the note folder and results folder

Select the approved folder containing the input notes, then select or accept a separate results folder. The note folder may contain subfolders, but it must contain only .txt notes. Keep XML, CSV, and other files outside it.

• Each filename begins with literal USDHUB plus exactly 20 digits.
• A period separates that HubID from a safe NoteID, followed by .txt.
• Letters, digits, periods, underscores, and hyphens are allowed inside NoteID; dots inside NoteID are valid.
• If the source names use PID or HID instead, use Prepare compatible copy. Preview the mapping and write a new private copy; do not rename the originals in place.

Run Check and read the summary

Choose Check run. This is a no-write preflight: it scans the note set, validates every filename, estimates storage, checks CPU and memory, and confirms the release-matched dictionary, WSD model, and SQLite driver. On a large folder, the summary is intentionally aggregated rather than printing thousands of repeated filename errors.

Confirm that the note count, folder, clinical settings, capacity, and storage estimate match what you intend to run. Start remains disabled until every required gate passes.

Confirm the clinical run and background handoff

Choose the Start button labeled with the note count, such as Start 100. Read the confirmation and continue only if the displayed folders, note count, and clinical settings are correct. The default is the STAR recipe, strict filenames, WSD on, SQLite plus two CSVs, XMI off, automatic capacity scaling, and final sanity checking.

The controller records the job before starting cTAKES and waits for a background-process handshake. Do not close the window until the confirmation says the background run has started.

Monitor progress, or leave and reconnect later

Runs & cTAKES logs shows the current phase, completed notes, elapsed time, rate, remaining-time estimate, CPU, memory, and storage. Sharded runs aggregate validated shard progress into the same job row. During startup, the total can temporarily show as unknown; rate and remaining time begin after notes finish.

Once the background-start handshake completes, leaving the TUI or losing the SSH session does not intentionally stop the controller. Reconnect and run ctakes tui to reopen the saved job. If the host or process actually stops, the TUI reconstructs the recorded state and offers recovery only from shards that validate against the same analysis and input identities.

Wait for PASSED, not only 100% notes

When all notes finish, the run can remain in CHECKING or FINALIZING while it builds indexes, exports the two CSVs, reads them back against SQLite, validates hashes and receipts, and writes the completion state. Accept the run only when it shows PASSED, the run manifest is complete, and the sanity report passes.

Review the checked result inside the TUI

Select the passed run and choose Open built-in viewer. The viewer opens the receipt-bound SQLite database and lets an approved reviewer page through notes, concepts, and medications. Selecting a row highlights its exact source phrase. No separate browser file is required.

Create the named copy of the two routine delivery CSVs

Return to the passed run and open Technical files. The screen explains the fixed artifacts and clearly labels partial files from failed or stopped runs. For a normal handoff, choose Create named CSV copy and enter the approved batch or test-run name.

The named-copy action rechecks both CSVs against the accepted SQLite views, writes owner-only copies whose filenames include the supplied run name, hashes them, and writes a small receipt. The canonical concepts.csv and drugs.csv remain unchanged.

Outputs and review lists every column in both delivery files and explains what each local artifact is used for.