Software Open Access

De-Identification Software Package

Published: Dec. 18, 2007. Version: 1.1


When using this resource, please cite the original publication:

Neamatullah I, Douglass M, Lehman LH, Reisner A, Villarroel M, Long WJ, Szolovits P, Moody GB, Mark RG, Clifford GD. Automated De-Identification of Free-Text Medical Records. BMC Medical Informatics and Decision Making, 2008, 8:32. doi:10.1186/1472-6947-8-32

Please include the standard citation for PhysioNet: (show more options)
Goldberger, A., Amaral, L., Glass, L., Hausdorff, J., Ivanov, P. C., Mark, R., ... & Stanley, H. E. (2000). PhysioBank, PhysioToolkit, and PhysioNet: Components of a new research resource for complex physiologic signals. Circulation [Online]. 101 (23), pp. e215–e220.

Background

In the USA, the HIPAA Privacy Rule restricts exchange of medical data containing protected health information (PHI), defined as any information that might be used to identify the individual(s) from whom the data were collected. Data known to contain PHI can be shared for research purposes only under tightly controlled circumstances, typically involving data use agreements under which the researchers involved must obtain IRB or equivalent approvals for use of the data.

By contrast, medical data that do not contain PHI are exempt from the restrictions of the HIPAA Privacy Rule and may be shared freely. The data available on PhysioNet fall into this category.

Many of the research data sets currently being collected by PhysioNet are accompanied by PHI, and the process of removing this PHI ("de-identification" in the language of HIPAA, or "anonymization") is tedious and error-prone. For many research projects, the cost of de-identification is a significant barrier to data sharing.

The MIMIC II project has invested several years' effort to develop and evaluate software that is capable of removing PHI from text and, where appropriate, replacing it by realistic surrogate PHI. (For example, names are replaced by fictitious names, medical record numbers by fictitious medical record numbers, dates by fictitious dates, geographic locations by other geographic locations, etc.) The MIMIC II project has contributed to PhysioNet both its deidentification software, which may be useful to other researchers needing to remove PHI from their own data, and a large corpus of text drawn from ICU nursing notes that were gathered simultaneously with the signals, trends, laboratory reports, discharge summaries and other data in the MIMIC II clinical and waveform databases.

Software

As is the case with all software available on PhysioNet, the de-identification software (deid) is provided in source form so that its workings can be studied, customized, and improved. This software is free software. You can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

The authors of the deid software package are Margaret M Douglass, Li-wei H Lehman, William J Long, and Ishna Neamatullah. An experimental prototype by Jason M Levine provided useful guidance in the design of deid.

Prerequisite

The deid package requires Perl (version 5 or later), which is freely available for all popular platforms here if you don't have it already.

The current version of the deid software package was developed and tested using perl 5.8.8 and perl 5.10 on GNU/Linux (Fedora Core 10). It has also been tested on Fedora 6, 7 and 8, Ubuntu 8.04, MacOS X 10.4.5, and on MS-Windows XP.

Downloading and installing deid

The deid software package can be downloaded as a single file, deid-1.1.tar.gz. The contents of deid-1.1.tar.gz unpack into a directory named deid-1.1, which contains the files listed below.

The deid software package is command-line software that must be run in a terminal emulator (console) window.

 

Testing deid

If you wish to test deid, see Data: the gold-standard corpus of deidentified medical text below for information on obtaining id.text and id.res. Copy id.text into the deid-1.1 directory (created when deid-1.1.tar.gz was unpacked in the previous step), and enter that directory. Type the command

perl deid.pl id deid.config

The software will print a greeting message:

    *******************************************************************************************************************
    De-Identification Algorithm: Identifies Protected Health Information (PHI) in Discharge Summaries and Nursing Notes
    *******************************************************************************************************************


    Starting de-identification (version 1.1) ...

    Running deid in output mode. Output files will be: 
    id.phi: the PHI locations found by the code.
    id.res: the scrubbed text.
    id.info: debug info about the PHI locations.

On a typical current PC, the process will run to completion in approximately 10 to 20 minutes. The three output files will be written into the current directory; they should be identical to the files of the same names that are included in the GSoutput directory.

The program runStat.pl can be used to derive performance statistics by comparing the id.phi file generated by deid.pl with the reference id.deid file provided with the deid software package. To do this, type the command

perl runStat.pl id.deid id.phi

which should produce the output

==========================

Num of true positives = 1720

Num of false positives = 546

Num of false negatives = 59

Sensitivity/Recall = 0.967

PPV/Specificity = 0.748

==========================

To use the gold standard corpus to test the performance of another deidentifier, arrange for that deidentifier to produce a file in the format of id.phi, then use runStat.pl as above.

Customizing deid

Examine the configuration file, deid.config, to see how to modify the behavior of deid.pl. For additional information, see the user manual.

In order to customize this software to de-identify free text in other medical records, you may replace our filter modules with your data-specific filters. Additionally, at a minimum, you will have to replace the six files that contain a priori information (see below).

Depending on the text you wish to de-identify, you may wish to re-classify names as ambiguous or not. For example, "Mae" is an unambiguous name in most contexts, but in nursing and discharge notes, it may be an acronym (meaning “moving all extremities”) and it is therefore ambiguous in those contexts.

Contents of the deid package

See above for information about downloading the entire deid package in a single archive file. The individual files in the package can also be viewed or downloaded by following the links below.

Code

  • deid.pl - perl program for de-identifying medical notes
  • runStat.pl - perl program for calculating performance statistics
  • stat.pm - perl subroutines shared by deid.pl and runStat.pl
  • deid.config - sample configuration file for use with deid.pl
  • COPYING - GNU General Public License, version 2

Dictionaries (see the User Manual for details)

  • dict/ Subdirectory containing lists of words and phrases not likely to be PHI
    • common_words.txt - 49,668 words that are common in medical records
    • commonest_words.txt - 5,126 words that are very common in medical records
    • medical_phrases.txt - 28 medical phrases
    • notes_common.txt - 66 very common words found in nursing notes
    • sno_edited.txt - 175,313 medical terms from UMLS/SNOMED
  • lists/ Subdirectory containing lists of words and phrases that are or might be PHI
    • Names
      • last_names_unambig.txt - 81,497 unambiguous family names
      • last_names_ambig.txt - 7,298 ambiguous family names
      • last_names_popular.txt - 93 popular family names
      • prefixes_unambig.txt - 17 family name prefixes (von, de la, etc.)
      • last_name_prefixes.txt - 138 prefixes that may appear before a family name
      • female_names_unambig.txt - 3843 unambiguous female given names
      • female_names_ambig.txt - 616 ambiguous female given names
      • female_names_popular.txt - 125 popular female given names
      • male_names_unambig.txt - 1144 unambiguous male given names
      • male_names_ambig.txt - 419 ambiguous male given names
      • male_names_popular.txt - 130 popular male given names
    • Locations
      • countries_unambig.txt - 179 country names
      • us_states.txt - 59 US states and territories
      • us_states_abbre.txt - 59 standard US state and territorial abbreviations
      • more_us_state_abbreviations.txt - 53 non-standard US state name abbreviations
      • locations_unambig.txt - 3341 unambiguous location names
      • locations_ambig.txt - 135 words that may be (parts of) location names
    • Other possible PHI
      • us_area_code.txt - 382 US telephone area codes
      • company_names_unambig.txt - 484 unambiguous company names
      • company_names_ambig.txt - 18 ambiguous company names
      • ethnicities_unambig.txt - 195 ethnicities
  • Known PHI (a priori information) - The six files in this group contain the surrogate PHI from the gold standard corpus, not the original PHI from the files used to create it! You will need to create your own versions of these six files, using these as models, if you wish to use deid on your own data.
    • pid_patientname.txt - 163 full names and ids of the patients in the gold standard corpus
    • doctor_first_names.txt - 56 given names of doctors
    • doctor_last_names.txt - 254 family names of doctors
    • stripped_hospitals.txt - 143 names of nearby hospitals
    • local_places_unambig.txt - 48 unambiguous names of nearby towns and cities
    • local_places_ambig.txt - 4 ambiguous names of nearby towns and cities
  • Files related to the gold-standard corpus (excluding a priori information, see above). The gold standard corpus itself must be obtained separately (see below); it is not part of this package.
    • id.deid - PHI locations in the gold standard corpus
    • id-phi.phrase - PHI locations, types, and PHI terms in the gold standard corpus
    • shift.txt - Date shifts for patients in the gold standard corpus
  • Sample outputs generated by deid.pl
    • id.phi - locations of detected PHI in the input text
    • id.res - the deidentified output text, with PHI replaced by tags
    • id.info - debugging information
    • GSoutput/ [The three files provided in this directory were generated from the gold standard corpus, using the test procedure described below running on Fedora 10.]
      • id.phi - locations of detected PHI in the input text
      • id.res - the deidentified output text, with PHI replaced by tags
      • id.info - debugging information
  • Documentation
    • doc/
      • DeidUserManual.pdf - De-Identification of Free-Text Medical Records: User Manual
      • Changes.log - Changes made since the initial release (deid-1.0).

Notes on the files in the package

Except for functions related to calculating performance statistics (in stats.pm), the deidentification code is contained in a perl script (deid.pl). Its configuration file, deid.config, can be used to set parameters of the deidentification process at run time. Associated word and phrase lists are in lists/ (containing known and possible PHI) and dict/ (containing probable non-PHI).

If the date shift filter is on, deid replaces all dates in its input with surrogate dates. The shift.txt file contains a randomly assigned date shift (between 1000 and 3000 days) for each patient in the gold standard corpus; surrogate dates are generated by adding the specified number of days to the dates in the input file. The method used to generate the date shifts in shift.txt differs from that used in PhysioBank databases.

The file id-phi.phrase is provided as a convenient index to the PHI in the gold standard corpus; it is not used by the deid software. Each line of this file contains 6 fields: PID, Record_Number, PHI_Start_Location, PHI_End_Location, PHI_Type, and PHI_Text.

The file id.deid also contains PHI locations in the gold standard corpus, and it is used as a reference for calculating performance statistics by the functions in stats.pm. It contains two types of lines. The first type is of the form

Patient PID Note Record_Number

and the second type is of the form

PHI_Start_Location PHI_Start_Location PHI_End_Location

Data: the gold-standard corpus of deidentified medical text

Evaluating software for de-identification turns out to be quite difficult. As in many of the projects contributing to PhysioNet, a reference database is highly useful. Ideally the developer of de-identification software needs an appropriate corpus of text in which all of the PHI has been labelled, so that the software's PHI detection performance can be assessed quickly and quantitatively. To compare different approaches to PHI removal objectively, we need a standard corpus. And here's the dilemma: we can't share such a corpus if it has any PHI in it!

The deid software package was developed and tested using a gold standard corpus of 2,434 nursing notes that have been thoroughly deidentified by a multi-pass process that included meticulous reviews by three or more experts working independently, as well as by a variety of automated methods. All detected instances of PHI in these nursing notes have been replaced by realistic surrogate data in the gold standard corpus. Although the deid software, as noted above, may be redistributed under the terms of the GPL, the gold standard corpus, because of the very small possibility that it may contain one or more instances of undetected PHI, is currently available only to those who have been granted access to PhysioNet Clinical Databases (such as MIMIC-III).

To apply for access to the gold standard corpus, please see the Deidentified Medical Text page.

Further reading

  1. Neamatullah I. Automated De-Identification of Free-Text Medical Records. MIT Dept of EECS, MEng thesis, 2006.
  2. Douglass M. Computer-Assisted De-identification of Free-text Nursing Notes. MIT Dept of EECS, MEng thesis, 2005.
  3. Douglass M, Clifford GD, Reisner A, Long WJ, Moody GB, Mark RG. De-Identification Algorithm for Free-Text Nursing Notes. Computers In Cardiology 32:331-334, 2005.
  4. Douglass M, Clifford GD, Reisner A, Moody GB, Mark RG. Computer-Assisted Deidentification of Free Text in the MIMIC II Database. Computers In Cardiology 31:341-344, 2004.
  5. Levine JM. De-identification of ICU patient records. MIT Dept of EECS, MEng thesis, 2003.

Acknowledgements

This work was performed with support from the National Institute of Biomedical Imaging and Bioengineering (NIBIB), under grant R01 EB001659.


Share
Access

Access Policy:
Anyone can access the files, as long as they conform to the terms of the specified license.

License (for files):
Open Data Commons Attribution License v1.0

Discovery
Corresponding Author
You must be logged in to view the contact information.

Files

Total uncompressed size: 0 B.

Access the files
Folder Navigation: <base>
Name Size Modified
GSoutput
GSstats
dict
doc
lists
COPYING (download) 17.6 KB 2019-04-12
README.txt (download) 10.4 KB 2019-04-12
deid-output.config (download) 5.2 KB 2019-04-12
deid.config (download) 5.2 KB 2019-04-12
deid.pl (download) 187.3 KB 2019-04-12
id-phi.phrase (download) 49.7 KB 2019-04-12
id.deid (download) 71.4 KB 2019-04-12
runStat.pl (download) 3.1 KB 2019-04-12
shift.txt (download) 1.8 KB 2019-04-12
stat.pm (download) 8.6 KB 2019-04-12