Variables

Overview

The TB Facility Register captures data for up to 5 patients per page. All fields are physically printed on the paper form. The sections below document every variable, its input type, whether it is required, any fill condition, validation constraints, and the OCR model used for automated recognition.

Note

Reading the tables

  • Required 705 — field must be completed for every patient row.
  • Conditional 001f500 — field is present on paper but should only be filled when a specific preceding answer is given (see the Fill Condition column).
  • OCR Model — the AI model ScanForm applies to recognise the handwritten or marked value. Fields with \u2014 are free-text handwriting zones not processed by OCR.

Field Types at a Glance

Field types across all variables
60 variables total
Input Type Count Share
⚪ Oval bubbles 37%
🔢 Digit boxes 25%
🔢 Digit box 8%
✏️ Handwriting 8%
☑️ Checkbox 7%
⚪ Oval bubble 7%
🔡 Letter/digit boxes 5%
🔡 Digit/letter boxes 3%

Variables by Section

Patient Identity (3) Registration (3) Demographics (3) Risk Group (2) Referral (1) Treatment (5) Initial Lab Results (9) Follow-up Smears (9) Imaging & DST (4) Treatment Outcome (4) HIV & ART (7) Post-TB / PRP (3) Other (1) Administrative (6)

Full Variable Reference

001faa6 Patient Identity

Patient Identity
Variable Label Input Type Required Conditional Fill Condition Format / Boxes OCR Model Constraint Notes
full_name Full Name Handwriting No No — 40 mm line — — Free text
full_address Address Handwriting No No — 40 mm line — — Free text
phone_number Phone Number Handwriting No No — 40 mm line — — Free text

001f4cb Registration

Registration
Variable Label Input Type Required Conditional Fill Condition Format / Boxes OCR Model Constraint Notes
tb_reg_date Registration Date Digit boxes Yes ✅ No — [][]/[][]/[2][0][][] date_dd x2, date_mm x2, int x2, date_nearby_yy x2 <= today() dd/mm/yyyy; century '20' pre-printed
participant_reg_id Participant Registration ID Digit/letter boxes No No — [][][][][]-[][][]-[][] int x8, string_restricted_BFGHJPVWXZ x2 regex alphanumeric Copied from TB Screening Form
tb_reg_number TB Registration Number Digit/letter boxes Yes ✅ No — [M][T][B]-[][][][][]-[][][]-[][] string x3, int x5, _record_int x3, _mtb_check_symbols x2 regex alphanumeric Prefix MTB- pre-printed
  • tb_reg_date format [][]/[][]/[2][0][][]: the digits 2 and 0 are pre-printed on the paper so staff write only the last two digits of the year.
  • tb_reg_number format [M][T][B]-[][][][][]-[][][]-[][]: the letters M, T, B are pre-printed; staff complete the numeric segments only.

001f464 Demographics

Demographics
Variable Label Input Type Required Conditional Fill Condition Format / Boxes OCR Model Constraint Notes
participant_age Age Digit boxes Yes ✅ No — 2 boxes int — Enter months if <2 yrs
participant_age_unit Y/M Digit box Yes ✅ No — 1 box _age_unit_check Y or M only Y = years, M = months
participant_sex Sex Oval bubbles Yes ✅ No — — select_one_or_zero — Male / Female

Write Y for years or M for months. If the patient is under 2 years old, record age in months and mark M.

6a00f Risk Group

Risk Group
Variable Label Input Type Required Conditional Fill Condition Format / Boxes OCR Model Constraint Notes
participant_risk Occupation / Risk Group Oval bubbles Yes ✅ No — — select_one_or_zero — Miner, Ex-Miner, Mining Community, HCW, Prisoner, HH Contact, Migrant, Other
participant_risk_other If Other, Specify Handwriting No No — 40 mm line — — Free text

001f3e5 Referral

Referral
Variable Label Input Type Required Conditional Fill Condition Format / Boxes OCR Model Constraint Notes
referral_source Referral Oval bubbles Yes ✅ No — — select_one_or_zero — Community, NCD, Private, Walk in, OPD, Ward, ART

001f48a Treatment

Treatment
Variable Label Input Type Required Conditional Fill Condition Format / Boxes OCR Model Constraint Notes
treatment_regimen Treatment Regimen Oval bubbles Yes ✅ No — — select_one_or_zero — 2RHZE/4RH, BPalM, BPal, Other
treatment_regimen_other Other Regimen Letter/digit boxes No Yes 🔀 treatment_regimen = 'regimen_other' 8 boxes string_int — Fill only if Other regimen selected
disease_site Site of Disease Oval bubbles Yes ✅ No — — select_one_or_zero — Pulmonary, Extra-Pulmonary
tb_history Treatment History Oval bubbles Yes ✅ No — — select_one_or_zero — New, Relapse, RALF, Fail, Other, Unknown
how_diagnosed Bact/Cl Diagnosed Oval bubbles Yes ✅ No — — select_one_or_zero — Bacteriologically, Clinically
Code Meaning
New New case
Relapse Previously treated — cured or completed
RALF Return after lost to follow-up
Fail Treatment after treatment failure
Other Previous treatment outcome unknown
Unknown Treatment history unknown

001f52c Initial Lab Results

Initial Lab Results
Variable Label Input Type Required Conditional Fill Condition Format / Boxes OCR Model Constraint Notes
lam_date LAM Date Digit boxes No No — [][]/[][]/[][] date_dd x2, date_mm x2, date_nearby_yy x2 — dd/mm/yy
lam_result LAM Result Oval bubbles No No — — select_one_or_zero — MTB Detected, MTB Not Detected
smear_date Smear Date Digit boxes No No — [][]/[][]/[][] date_dd x2, date_mm x2, date_nearby_yy x2 <= today() dd/mm/yy
smear_result Smear Result Digit box No No — 1 box int 0-9 Count; see smear_plus for grade
smear_plus Smear Plus Oval bubble No No — — select_one_or_zero — Mark + if 1+, 2+ or 3+; leave blank if 0 or exact count
xpert_date Xpert Date Digit boxes No No — [][]/[][]/[][] date_dd x2, date_mm x2, date_nearby_yy x2 <= today() dd/mm/yy
xpert_result Xpert Result Oval bubbles No No — — select_one_or_zero — MTB Detected, MTB Not Detected
culture_date Culture Date Digit boxes No No — [][]/[][]/[][] date_dd x2, date_mm x2, date_nearby_yy x2 <= today() dd/mm/yy
culture_result Culture Result Oval bubbles No No — — select_one_or_zero — MTB Detected, MTB Not Detected

smear_result accepts a digit (00139) representing the bacilli count. The accompanying smear_plus oval should be crossed only when the grade is 1+, 2+, or 3+. Leave the oval blank when recording an exact count or a result of 0.

001f52c Follow-up Smears

Follow-up Smears
Variable Label Input Type Required Conditional Fill Condition Format / Boxes OCR Model Constraint Notes
smear_date_2 Smear Date - 2 month Digit boxes No No — [][]/[][]/[][] date_dd x2, date_mm x2, date_nearby_yy x2 <= today() dd/mm/yy
smear_result_2 Smear Result - 2 month Digit box No No — 1 box int 0-9 —
smear_plus_2 Smear Plus - 2 month Oval bubble No No — — select_one_or_zero — Mark + if 1+, 2+ or 3+
smear_date_5 Smear Date - 5 month Digit boxes No No — [][]/[][]/[][] date_dd x2, date_mm x2, date_nearby_yy x2 <= today() dd/mm/yy
smea_result_5 Smear Result - 5 month Digit box No No — 1 box int 0-9 ⚠️ Typo in variable name: smea_result_5
smear_plus_5 Smear Plus - 5 month Oval bubble No No — — select_one_or_zero — Mark + if 1+, 2+ or 3+
smear_date_6 Smear Date - 6 month Digit boxes No No — [][]/[][]/[][] date_dd x2, date_mm x2, date_nearby_yy x2 <= today() dd/mm/yy
smear_result_6 Smear Result - 6 month Digit box No No — 1 box int 0-9 —
smear_plus_6 Smear Plus - 6 month Oval bubble No No — — select_one_or_zero — Mark + if 1+, 2+ or 3+
Warning

smea_result_5 contains a typo in the variable name (missing letter r). Data pipelines must reference this exact name.

001f9fb Imaging & DST

Imaging & DST
Variable Label Input Type Required Conditional Fill Condition Format / Boxes OCR Model Constraint Notes
xray_date XRay Date Digit boxes No No — [][]/[][]/[][] date_dd x2, date_mm x2, date_nearby_yy x2 <= today() dd/mm/yy
xray_result XRay Result Oval bubbles No No — — select_one_or_zero — MTB Detected, MTB Not Detected
dst_date DST Date Digit boxes No No — [][]/[][]/[][] date_dd x2, date_mm x2, date_nearby_yy x2 <= today() dd/mm/yy
dst_result DST Result Oval bubbles No No — — select_one_or_zero — RIF Resistant Detected, RIF Resistant Not Detected, RIF Resistant Indeterminate

001f4ca Treatment Outcome

Treatment Outcome
Variable Label Input Type Required Conditional Fill Condition Format / Boxes OCR Model Constraint Notes
treat_outcome Treatment Outcome Oval bubbles No No — — select_one_or_zero — Cured, Treatment Completed (No smear), Dead, Treatment Failure, Lost to Follow-up, Not Evaluated
outcome_date Outcome Date Digit boxes No No — [][]/[][]/[][] date_dd x2, date_mm x2, date_nearby_yy x2 <= today() dd/mm/yy
second_line Moved to 2nd Line Tx Oval bubbles No No — — select_one_or_zero — Yes, No
adherence_support DOT and Adherence Support Oval bubbles No No — — select_one_or_zero — GUA, HSA, VOL, HCW

001f534 HIV & ART

HIV & ART
Variable Label Input Type Required Conditional Fill Condition Format / Boxes OCR Model Constraint Notes
hiv_status HIV Status Oval bubbles Yes ✅ No — — select_one_or_zero — Pos, Neg, Unk
hiv_test_time HIV Test Time Oval bubbles No Yes 🔀 hiv_status = 'positive' or hiv_status = 'negative' — select_one_or_zero — Before TB Reg, After TB Reg
arv_status ARV Start Time Oval bubbles No Yes 🔀 hiv_status = 'positive' — select_one_or_zero — Before TB Tx, While on TB Tx, Not While on TB Tx
arv_id ARV No. Letter/digit boxes No Yes 🔀 arv_status = 'before_tb' or arv_status = 'while_on_tb' 13 boxes string_int regex alphanumeric —
art_reg_id ART Registration ID Letter/digit boxes No Yes 🔀 hiv_status = 'positive' [A][R][T]-[][][][][]-[][][]-[][] string x3, int x8, string_restricted_BFGHJPVWXZ x2 regex alphanumeric Prefix ART- pre-printed
cpt_status CPT Status Oval bubbles No Yes 🔀 hiv_status = 'positive' — select_one_or_zero — Yes, No
cpt_start_date CPT Start Date Digit boxes No Yes 🔀 cpt_status = 'yes' [][]/[][]/[][] date_dd x2, date_mm x2, date_nearby_yy x2 <= today() dd/mm/yy

Several fields are only relevant when HIV is confirmed positive. Complete them only when hiv_status = Pos:

  • arv_status — ARV Start Time
  • art_reg_id — ART Registration ID (ART- pre-printed)
  • cpt_status — CPT Status
  • cpt_start_date — CPT Start Date (additionally requires cpt_status = Yes)
  • arv_id — ARV No. (additionally requires arv_status = Before TB Tx or While on TB Tx)

hiv_test_time should be completed when HIV status is Pos or Neg.

001fac1 Post-TB / PRP

Post-TB / PRP
Variable Label Input Type Required Conditional Fill Condition Format / Boxes OCR Model Constraint Notes
enrolled_prp Enrolled into PRP Oval bubbles No Yes 🔀 treat_outcome = 'cured' or treat_outcome = 'completed' — select_one_or_zero — Yes, No
ptld_how_diagnosed PTLD Diagnosis Method Oval bubbles No Yes 🔀 enrolled_prp = 'yes' — select_one_or_zero — Spirometry/LFT, Persistent Respiratory Symptoms, Abnormalities Xray, Reduced Exercise
prp_outcome PRP Outcome Oval bubbles No No — — select_one_or_zero — Completed, Died, Lost to Follow-up, Active TB, Excluded

enrolled_prp is filled only when treat_outcome is Cured or Completed. If enrolled, ptld_how_diagnosed records the diagnostic method. prp_outcome is completed for all PRP patients regardless of enrolment route.

001f4dd Other

Other
Variable Label Input Type Required Conditional Fill Condition Format / Boxes OCR Model Constraint Notes
comments Comments Handwriting No No — 40 mm line — — Free text

6990f Administrative

Administrative
Variable Label Input Type Required Conditional Fill Condition Format / Boxes OCR Model Constraint Notes
book_number Book Number Digit boxes No No — 5 boxes — — Page-level field
page_number Page Number Digit boxes No No — 3 boxes — — Page-level field
photo_taken Photo Taken Checkbox No No — — — — Confirms scan photo captured
discard_page Discard Left & Right Page Checkbox No No — — — — Marks entire page as discarded
discard_row Discard Row Checkbox No No — — — — Marks individual patient row as discarded
implementation_error Implementation Error Checkbox No No — — — — Flags a data entry error
  • Book Number (5 boxes) and Page Number (3 boxes) are page-level identifiers shared by all 5 patient rows on the page.
  • Photo Taken, Discard Left & Right Page, Discard Row, and Implementation Error are trigger checkboxes — they carry no free-text value and are not processed by OCR.

Conditional Logic Map

Conditional fields — fill only when condition is met
9 of 60 variables are conditional
Variable Label Section Fill Condition
treatment_regimen_other Other Regimen Treatment treatment_regimen = 'regimen_other'
hiv_test_time HIV Test Time HIV & ART hiv_status = 'positive' or hiv_status = 'negative'
arv_status ARV Start Time HIV & ART hiv_status = 'positive'
arv_id ARV No. HIV & ART arv_status = 'before_tb' or arv_status = 'while_on_tb'
art_reg_id ART Registration ID HIV & ART hiv_status = 'positive'
cpt_status CPT Status HIV & ART hiv_status = 'positive'
cpt_start_date CPT Start Date HIV & ART cpt_status = 'yes'
enrolled_prp Enrolled into PRP Post-TB / PRP treat_outcome = 'cured' or treat_outcome = 'completed'
ptld_how_diagnosed PTLD Diagnosis Method Post-TB / PRP enrolled_prp = 'yes'

OCR Models Used

OCR models deployed in this form
Each row-cell pair may use a distinct model per character box
OCR Model Fields Using Category
📄 Other
int x8 Other
string x3 Other
int x2 Other
int x5 Other
🔧 Custom / Local
_age_unit_check Custom / local
_mtb_check_symbols x2 Custom / local
_record_int x3 Custom / local
🔡 Restricted
string_restricted_BFGHJPVWXZ x2 Restricted alphabet
📅 Date Component
date_dd x2 Date component
date_mm x2 Date component
date_nearby_yy x2 Date component
🔢 General
int General
string_int General
⚪ Oval / Select
select_one_or_zero Oval / select
Model What it recognises
select_one_or_zero Oval bubbles: detects X or blank; at most one X per question
int Digits 00139
string Letters A013Z
string_int Letters A013Z and digits 00139
date_dd Two-digit day (101331)
date_mm Two-digit month (101312)
date_nearby_yy Two-digit year near current year (0b11)
string_restricted_BFGHJPVWXZ Restricted letter set used in ID codes to avoid OCR confusion
_age_unit_check Custom local model: Y or M only
_record_int, _mtb_check_symbols Custom local models for TB registration number validation

Required vs Optional Fields