Introduction

The NamePhonetics module provides a number of soundex algorithms from the apache commons codec project, and supports plugging in any custom soundex-like algorithm. The included algorithms are currently Soundex, Refined Soundex, Metaphone, Double Metaphone, Caverphone, Kinyarwanda, and a port of a custom Chichewa algorithm originally developed for the ART system in Malawi by Baobab Health and PIH.

What this Module Does

The namephonetics module provides service methods and a data model for finding a patient based on an algorithmic name match.

What this Module Doesn't Do

The module doesn't change the default patient lookup in OpenMRS. But the module does have a bunch of API methods for finding a patient and a supporting data model, and is currently integrated into the primary care touchscreen registration system developed and piloted by PIH in Rwanda.

To use this functionality in your own application, you'd want to download the omod here, change the extension to .jar, and then include this as a resource in your own module.

Administration

These settings (formerly Global Properties from 1.8 downwards) are available:

namePhonetics.givenNameStringEncoder
namePhonetics.middleNameStringEncoder
namePhonetics.familyNameStringEncoder
namePhonetics.familyName2StringEncoder

and the available valid values by default are:

Soundex
Refined Soundex
Metaphone
Double Metaphone
Caverphone
Chichewa
Kinyarwanda
(If you plug in your own algorithm via another module, the name property of this algorithm will also be a valid value.)

There is a jsp page to re-compute the encoder values for all patients.

Adding Your Own Encoding Algorithm

The module allows you to add your own algorithm. All algorithms only have to be an extension of the StringEncoder class that lives in the apache commons codec jar file. The module also includes all the algorithms that live in this jar file by default – Soundex, RefinedSoundex, Metaphone, Double Metaphone. The encoder classes for Chichewa and Kinyarwanda are good places to start, if you'd like to write your own encoder. If you do write your own, please remember to add your encoder to the list in metadata/moduleApplicationContext.xml when the encoder class itself is ready.

Technical Description

Each row in the module's table stores one encoded name component, which is then labeled by a java enum (GIVEN_NAME, MIDDLE_NAME, FAMILY_NAME, FAMILY_NAME2). The module AOP's around PatientService.savePatient and calculates the code for fields that you specify using a global property, meaning that you can control which PersonName fields you want to encode, and you can even attach them to different soundex algorithms (folks in Rwanda get a local name and a christian name, which are quite different).

The Chichewa soundex was ported directly into java, which is included in the module, and was used as a basis for Kinyarwanda.

Resources

keywords: soundex, metaphone, name encoder

Documentation

NamePhonetics Module