Plain Text Labs

Description

Beancount for lab reports. Store your lab results as plain text and analyze them in your terminal.

Features

• Simple plain-text format for lab results
• Track lab values over time
• Include reference ranges
• Organize results across multiple files with include directive
• Define aliases to group tests with different names (e.g., "TSH" and "Thyroid Stimulating Hormone")
• Powerful query language for filtering and analyzing results
• Filter to show only tests with out-of-range values
• Automatic trend analysis and charts for tests over time
• Color-coded output (green for in-range, red for out-of-range)
• Terminal UI (TUI) with interactive visualization and charts

Installation

# Build everything (CLI + TUI)
cargo build --release --workspace

# Build only CLI
cargo build --release -p plaintextlabs-cli

# Build only TUI
cargo build --release -p plaintextlabs-tui

Usage

Command-Line Interface (CLI)

Display all lab results:

plaintextlabs sample.lab

Query lab results:

# Find specific tests
plaintextlabs sample.lab "test = Glucose"

# Use wildcards in test names
plaintextlabs sample.lab "test = chol*"
plaintextlabs sample.lab "test = *ldl*"

# Filter by date range
plaintextlabs sample.lab "date >= 2024-01-01 AND date <= 2024-03-31"

# Find abnormal values
plaintextlabs sample.lab "value < ref.min OR value > ref.max"

# Complex queries
plaintextlabs sample.lab "(test = Glucose OR test = LDL) AND value > ref.max"

Show only tests with out-of-range values:

# Show all entries for tests that have any out-of-range values
plaintextlabs sample.lab --out-of-range

# Combine with queries
plaintextlabs sample.lab "date >= 2024-01-01" --out-of-range

When using --out-of-range, if a test has at least one out-of-range value, all entries for that test are shown (including in-range ones). This helps you see the full history of problematic tests.

Wildcard matching:

Use * in test name queries to match any characters:

# Match tests starting with "chol"
plaintextlabs sample.lab "test = chol*"
# Matches: Cholesterol, Cholesterol Total, etc.

# Match tests ending with "sterol"
plaintextlabs sample.lab "test = *sterol"
# Matches: Cholesterol, etc.

# Match tests containing "ldl"
plaintextlabs sample.lab "test = *ldl*"
# Matches: LDL, LDL-Cholesterol, VLDL, etc.

# Match any test
plaintextlabs sample.lab "test = *"

Terminal User Interface (TUI)

For interactive visualization and exploration of your lab results:

plaintextlabs-tui sample.lab

Features:

• Master-detail interface with test list and detailed views
• Two-tab interface:
  • Table: Detailed table view with all test results
  • Chart: Scatter plot visualization with reference ranges
• Visual reference range indicators on charts
• Color-coded out-of-range highlighting
• Vim-style keyboard navigation (hjkl or arrow keys)
• Press q to quit

See plaintextlabs-tui/README.md for more details.

File Format

Create a .lab file with your patient metadata and lab results:

dob: 1989-05-20
sex: M

2024-01-15 Glucose: 95 mg/dL [ref: 70-100]
2024-01-15 Cholesterol: 180 mg/dL [ref: 0-200]

Organizing with Multiple Files

Keep your lab results organized by using includes:

my-labs.lab:

dob: 1989-05-20
sex: M

include "labs/2024-q1.lab"
include "labs/2024-q2.lab"

labs/2024-q1.lab:

# Q1 2024 Results
2024-01-15 Glucose: 95 mg/dL [ref: 70-100]
2024-03-15 Glucose: 92 mg/dL [ref: 70-100]

Grouping Tests with Aliases

Different labs often use different names for the same test. Use aliases to group these together:

common-aliases.lab:

# Common test name aliases
alias: TSH = TSH; Thyroid Stimulating Hormone; Thyrotropin
alias: LDL = LDL; LDL Cholesterol; LDL-C
alias: HbA1c = Hemoglobin A1c; HbA1c; A1C; Glycated Hemoglobin

my-labs.lab:

dob: 1989-05-20
sex: M

include "common-aliases.lab"

# Lab Corp uses "TSH"
2024-01-15 TSH: 2.1 mIU/L [ref: 0.4-4.5]

# Quest uses "Thyroid Stimulating Hormone"
2024-06-15 Thyroid Stimulating Hormone: 2.3 mIU/L [ref: 0.4-4.5]

The tool will automatically group these together and calculate trends across both tests.

See FORMAT.md for complete format specification.

Converting PDFs to .lab Format

You can use AI assistants like Claude to convert lab result PDFs into the .lab format. Simply upload your PDF and use this prompt:

Please extract all lab results from this PDF and format them in the plaintextlabs format.

Use this format for each entry:
YYYY-MM-DD TestName: value unit [ref: min-max]

Rules:
- Use ISO 8601 dates (YYYY-MM-DD)
- Keep test names as they appear in the PDF
- Include units after the value (mg/dL, mmol/L, etc.)
- Add reference ranges in square brackets using one of these formats:
  [ref: min-max] for ranges like 70-100
  [ref: >value] for "greater than" thresholds like >60
  [ref: <value] for "less than" thresholds like <5
- For text values (like NEGATIVE, POSITIVE, YELLOW), just write the text without a unit
- Skip the reference range if not provided in the PDF
- Keep results in the order they appear

Start the file with:
dob: YYYY-MM-DD
sex: M or F

Then list all test results, one per line.

Output only the formatted lab results, with no additional commentary.

Example result:

dob: 1989-05-20
sex: M

2024-03-15 Glucose: 95 mg/dL [ref: 70-100]
2024-03-15 Hemoglobin A1c: 5.2 % [ref: <5.7]
2024-03-15 eGFR: 95 mL/min/1.73m2 [ref: >60]
2024-03-15 Total Cholesterol: 185 mg/dL [ref: 0-200]
2024-03-15 HDL Cholesterol: 55 mg/dL [ref: >40]
2024-03-15 LDL Cholesterol: 110 mg/dL [ref: <100]
2024-03-15 Triglycerides: 100 mg/dL [ref: 0-150]
2024-03-15 TSH: 2.1 mIU/L [ref: 0.4-4.5]
2024-03-15 Vitamin D: 42 ng/mL [ref: 30-100]
2024-03-15 Urine Color: YELLOW
2024-03-15 Urine Glucose: NEGATIVE

Save the output to a .lab file and you're ready to analyze your results.