SmartVA Keyword and Free-Text Processing

This document explains how SmartVA extracts diagnostic signals from narrative text and keyword selections in the WHO 2022 VA form. Understanding this processing is essential for interpreting results, especially in multilingual deployments.

Overview

SmartVA has two mechanisms for extracting cause-related information from narrative responses:

Both mechanisms contribute symptom features that feed into the tariff-based cause scoring algorithm.

WHO 2022 Narrative Fields

Field Definitions

Processing Flow

Id10476 (text)     →  Word extraction  →  s9999* variables
                         (English only)

Id10477 (choices)  →  One-hot encoding →  adult_7_* variables
Id10478 (choices)  →  One-hot encoding →  child_6_* variables
Id10479 (choices)  →  One-hot encoding →  neonate_6_* variables

Free-Text Word Extraction

Source Files

Processing Pipeline

1. Normalize text (common_prep.py:293-310)

   # Lowercase, remove non-alphabetic characters
   words = re.sub('[^a-z ]', '', row[variable].lower()).split(' ')
   

2. Apply word substitutions (WORD_SUBS dictionary)

   • Corrects common misspellings
   • Normalizes variants to canonical forms

3. Stem words (Porter2 stemmer)

   stem("fever")     → "fever"
   stem("fevers")    → "fever"
   stem("diabetes")  → "diabet"
   stem("diabetic")  → "diabet"
   

4. Map to symptom variables (word_conversions.py)

   ADULT_WORDS_TO_VARS = {
       'fever': 's999969',
       'cancer': 's999927',
       'stroke': 's9999146',
       'suicide': 's9999148',
       # ... 172 total mappings
   }
   

5. Set binary flags

   row['s999969'] = 1  # if "fever" found in narrative
   

Word Substitutions (common_data.py:451-557)

The WORD_SUBS dictionary maps misspellings and variants to canonical forms:

Adult Word Mappings (word_conversions.py:1-173)

172 English word stems map to s9999* variables:

Child Word Mappings (word_conversions.py:175-225)

55 word stems for child analysis:

Neonate Word Mappings (word_conversions.py:227-265)

38 word stems for neonate analysis:

Keyword One-Hot Encoding

Source File

vendor/smartva-analyze/src/smartva/data/who_data.py:391-420

Processing Logic

The ONE_HOT_FROM_MULTISELECT dictionary maps (WHO field, choice value) pairs to binary PHMRC-style variables:

ONE_HOT_FROM_MULTISELECT = {
    'adult_7_1': ('Id10477', 'Chronic_kidney_disease'),
    'adult_7_2': ('Id10477', 'Dialysis'),
    # ...
}

When processing:

# If Id10477 contains "Fever" in its space-separated value list
row['adult_7_3'] = 1  # else 0

Adult Keywords (Id10477 → adult_7_*)

Child Keywords (Id10478 → child_6_*)

Neonate Keywords (Id10479 → neonate_6_*)

Language Handling

Free-Text Processing (Id10476)

English only. The word extraction pipeline:

1. Relies on English word stems in ADULT_WORDS_TO_VARS
2. Uses English-specific Porter2 stemmer
3. Applies English misspelling corrections in WORD_SUBS

Example:

English:  "Patient had fever and cough for 2 weeks"
          → s999969=1 (fever), s999946=1 (cough)

Hindi:    "रोगी को दो सप्ताह से बुखार और खांसी थी"
          → No s9999* variables set

Keyword Processing (Id10477-10479)

Language independent. ODK stores choice values, not display labels:

This means keyword selections work correctly regardless of the language used during data collection.

Context Problem: Negation and Qualifiers

The Fundamental Issue

SmartVA's word extraction is context-blind. It detects word presence but does not understand:

• Negation: "no fever", "denied fever", "never had fever"
• Qualifiers: "possible fever", "rule out fever"
• Temporal context: "fever 5 years ago (unrelated)"
• Family history: "father had fever"

Examples of Misclassification

Why This Matters

The tariff scoring algorithm adds points for symptom endorsements. A false positive (word detected but symptom absent) can:

1. Inflate scores for causes that include that symptom
2. Dilute the signal from genuinely present symptoms
3. Mislead coders who see keyword flags in the UI

Mitigation Strategies

1. Keyword fields are safer: The select_multiple fields (Id10477-10479) require active selection, avoiding negation issues.

2. Coders should read full narrative: Free-text flags are hints, not definitive. The actual narrative may contain negations.

3. Training emphasis: Coder training should emphasize that SmartVA keywords are presence-detected, not context-aware.

4. Future improvement options:

   • Negation detection (NLP preprocessing)
   • Require keyword confirmation in structured field
   • Use --freetext=False to disable problematic extraction

Configuration: --freetext Flag

Effect on Analysis

The --freetext CLI flag controls whether free-text variables are included in tariff scoring:

smartva --freetext=True   # Include s9999* variables (default)
smartva --freetext=False  # Exclude s9999* variables

In DigitVA

Passed to SmartVA module in va_smartva_03_runsmartva.py:

cmd = [
    sys.executable, "-m", "smartva.va_cli",
    "--freetext", va_form.form_smartvafreetext,  # "True" or "False"
    # ...
]

When to Disable Free-Text

Consider --freetext=False if:

1. Non-English narratives: 0% of s9999* variables will be set anyway
2. Negation-heavy narratives: Context problems outweigh benefits
3. Inconsistent narrative quality: Reduces noise in scoring

Impact Assessment

Multilingual Deployment Recommendations

Current Setup Assessment

With mixed-language data (English, Hindi, Kannada, Malayalam):

Recommendations

1. Keep freetext=True: No harm for non-English; benefit for English submissions

2. Emphasize keyword fields in training: Ensure coders use Id10477-10479 selections rather than relying on narrative text

3. Document language limitations: Coders should understand that non-English narratives do not contribute to SmartVA scoring

4. Consider structured alternatives: If critical diagnostic information is being lost, add more structured questions to the ODK form

Future Enhancement Options

To enable non-English free-text processing:

1. Add language-specific word mappings to word_conversions.py:

   HINDI_WORDS_TO_VARS = {
       'बुखार': 's999969',  # fever
       'कैंसर': 's999927',  # cancer
       # ...
   }
   

2. Add language-specific substitutions to WORD_SUBS

3. Detect language and route to appropriate mapping

4. Requires linguistic expertise and validation testing

Summary Table

Related Documentation

• smartva-analysis.md — Overall SmartVA integration in DigitVA
• data-model.md — va_smartva_results table schema
• odk-sync.md — How SmartVA is triggered during sync