Automated HVF Grading

Humphrey Visual Field matrix reading, grading and analysis automated via python for research at Flinders University

Supporting library:

hvf_extraction_script

Features

---

• algorithm to automate reading hvf % pattern deviation field scans
• data filtering such as sorting eye by left and right, patient name, chronological order
• automating progression of glaucoma: we can chronologically map past outcomes and apply progressor criteria (see below) to detect an onset
• parallel processing: runParallel function allows us to run jobs simulatenously on multi-core computer saving time for huge file batches by using full cpu processing capabilities
• your choice of how you use it. Directly through the module, a CLI or via a GUI

Usage

This library can be used in 3 ways:

Methods 1 and 2 require the setup of a conda environment

1. Directly through the module

Install the library by running pip install . in the root of the repo. Then you can import the library and use it in your code.

2. From the CLI

Run python automated_hvf_grading/cli.py in the root of the repo.

3. Using an easy to use GUI

The Electron based GUI is a wrapper of the CLI. It is bundles with a python environment You can download it from the [releases page] Coming soon

Regions

Recent Changes

---

• rewrote entire repository from ground up!
• improved error messages and error checking
• all user bug fixes resolved (7/8 tested)
• more reliable extraction
• more extraction features
• many more features
• improved parallel processing takes full advantage of cpu: program can now process large file batches very quickly on multi-core cpu's

Algorithmic Criteria

---

An eye was deemed to have progressed if there was a new cluster of visual field defects that were reproduced in a consecutive field (but not necessarily the same visual field locations). A cluster of visual field defects was defined as 3 contiguous points abnormal in the pattern deviation probability plot at P < 5%, at least one of which is P< 1%. If the GHT was “Outside Normal Limits” or the global PSD was P < 5% on the two consecutive HVFs, then the individual points only needed to be abnormal on the pattern deviation probability plot at P < 5%.

In other words:

category 2) A cluster of at least 3 contiguous points in the same region depressed at P < 5%, with at least one these < 1%

category 3) A cluster of at least 3 contiguous points in the same region depressed at P < 5% AND (GHT = Outside Normal Limits OR PSD = P < 5%)

Terminology

abnormal: there is a defect in eye as given algorithmic criteria is satisfied

reliable: data is reliable if and only if false pos and fixation loss are both less than 33%

error: this is a flag to mark that there may be an error present in result due to not being able to extract every feature consequently leading to unreliable dependencies

confirmation field: "2/3 consecutive chronological defects in the same region" 

Progrssion in eye was deemed to have progressed if there was a new cluster of visual field defects that were reproduced in a consecutive field (but not necessarily the same visual field locations). A cluster of visual field defects was defined as 3 contiguous points abnormal in the pattern deviation probability plot at P < 5%, at least one of which is P< 1%. If the GHT was “Outside Normal Limits” or the global PSD was P < 5% on the two consecutive HVFs, then the individual points only needed to be abnormal on the pattern deviation probability plot at P < 5%. 

progressor criteria: any 2 defective scans out of 3 consecutive chronological samples

Progression column: output is determined as true if the progression criteria listed above is satisfied

Progression onset: date of the first recorded progression

Short hand terminology

---

matrix sub-regions: ul, ll, um, uc, lc, lm, ur, lr upper left, lower left, upper middle, upper central, lower central, lower middle, upper right, lower right final output listed as equivalent medical terms

Location labels

left eye "UL": "Superior temporal wedge", "LL": "Inferior temporal wedge", "UM": "Superior Bjerrum", "UC": "Superior paracentral", "LC": "Inferior paracentral", "LM": "Inferior Bjerrum", "UR": "Superior nasal step", "LR": "Inferior nasal step",

right eye "UL": "Superior nasal step", "LL": "Inferior nasal step", "UM": "Superior Bjerrum", "UC": "Superior paracentral", "LC": "Inferior paracentral", "LM": "Inferior Bjerrum", "UR": "Superior temporal wedge", "LR": "Inferior temporal wedge",

left eye

right eye

To-do

• refactor code using OOP

• refactor into a modules

• get driver.py to run

• fix criteria in algorithm (< 5 % not 0.5 %)

• get extraction to work

• refactor: remove temp_dictionary and use patientData class

• refactor: make dataFrame class and have dataFrame methods

• refactor analyseData, build dataFrame into DataFrame class

• create subdf for specific patient

• work on creating sub_dfs for left and right eye

• add medical terms to sub_df title

• sort chronologically just before applying progrssor criteria on subdf for given patient

• fix progression analysis function

• add date of first progression to column

• fix two differnt vfi labels through pattern matching

• processed files changed to file runner

• work on creating a new object for each user object file run as objects previous values get carried across https://stackoverflow.com/questions/21598872/how-to-create-multiple-class-objects-with-a-loop-in-python

• create driver functions for both concurrent and parallel jobs (8 cores) in driver.py

• parallel environment working

• progression functionality seperated

• filter out N/A on dfs

• add filtering to progressor criteria

• change progressor criteria to take in object

• all functions return progObject

• recheck criteria according to email in processData

• grade trial folder and send results to Nia

Extensions

• get working for 32-2 pdfs
• progressor criteria runs only on scans where reliable = True and error = False, add filtering on dataframe to remove invalid scans

Intial bug fixes based on user requirements

• MD% and PSD% in the criteria for abnormal (criteria 3) [Fix psd < 5%]

• region defect not detected upon criteria 2 and 3 (see file error2.pdf)

• location labels mixed up (nasal step labeled as temporal wedge)

• more specific and reliable error messages

• extraction failure labels (unable to extract -> more specific label: 'too severe to analyse')

• VFI extraction (VFI24-2 and VFI are varying formats)

• reliability = FNeg, FPos, FLoss all < 33 %

• Progression column: comment on what determined whether output if true or false

• Progression analysis inconsistent (errors sometimes occur)

• Error: ght unable to be extracted type object 'Hvf_Object' has no attribute 'KEYLABEL_GHT'

• Error: metadata md % not able to be extracted type object 'Hvf_Object' has no attribute 'KEYLABEL_MDP'

• Error: metadata psd % not able to be extracted type object 'Hvf_Object' has no attribute 'KEYLABEL_PSDP'

GUI / Sonel

• parseDataFrame run data is not defined
• False negatives (list reliability index on GUI)
• highlight/ 'select' a row of the table (ie an individual field) to make it easy to track when scrolling across
• column headings should be locked so when scrolling down the rows these still stay at the top
• implement a more intuitive drop down filter for right and left eye
• absolutely all user object variables displayed on GUI output
• integrate parallel joblib up to 7 jobs for parallel processor for 8 core cpu
• filter by eye left and right integration
• psd % readings extremely inconsistent -- improve readings
• false_neg_perc sometimes comes out as N/A in extraction on occasions -- needed to determine reliability

notes / issues

---

sample field attached to email_

• the issue with errorSample is that the psd % cannot be properly read or ght.Therefore we cannot determine if criteria 3 is valid so I coded the algorithm to default to criteria 2

• progressor criteria not testing on a large sample size -- could still need work

• run time: takes about 36 seconds to completely extract, analyse and asses 20 samples: 1.8 per sample on average (parallel dispatching speeds this up though)

• mixed up hemifields as left and right eyes have differnt hemifields and the extraction is a mixed samples of both left and right eyes then in order to process it we need to divide data frame into left and right eyes seperately before we apply progressor criteria or labelling

To solve this problem, hemifield labels are converted with a map and will not be labelled until data is split into sub-data frames by eye

• we are extracting only pattern deviation matricies however this package is capable of extracting, processing and analysing other matricies

• Some PDF are corrupt and will always fail to be processed (tesseract)

• ght is commonly unable to be extracted, the extraction mechanism/code should be looked into in more detail

Developer Setup

---

To create the environment: Install either Conda or Miniconda(used to create prebuilt binares) and run the following commands

conda create --name ENV_NAME regex pillow fuzzywuzzy pandas python-levenshtein numpy joblib IPython
conda activate ENV_NAME
conda install -c conda-forge tesserocr
pip install -r requirements.txt

To install the modified hvf_extraction_library:

# navigate to /hvf_extraction_script (modified)
pip install . (OR python setup.py install / develop)

Packing env for use in front end using conda-pack:

conda install conda-pack
conda pack -n ENV_NAME -o env.zip