SimpleICD10-Java-edition

A simple Java library for ICD-10 codes

Index

Release notes
Introduction
Setup
What a code is and how it looks like
Documentation
Conclusion

Release notes

1.0.1: Renamed package: "it.trv.simpleicd10" -> "it.trvi.simpleicd10"
1.0.0: Initial release

Introduction

The scope of this library is to provide a simple instrument for dealing with ICD-10 codes in your Java projects. It provides ways to check whether a code exists, to find its ancestors and descendants, to see its description and much more.
The codes and their descriptions were taken from this page in the WHO's website and are referred to the 2019 version of ICD-10.
If you are looking for a library that deals with ICD-10 codes instead of ICD-10-CM codes, you can check the SimpleICD10CM-Java-edition library, which is based on the 2019 version of ICD-10.
If you are looking for a Python version of this project, you can check the simple_icd_10 library.

In the "data" folder you can find an XML file that contains the entire ICD-10 classification.

All the classes in this library are contained in the package "it.trvi.simpleicd10".

Setup

You can download the jar containing the most recent recent version of this library from the releases page on Github.

What a code is and how it looks like

We need to start by clarifying what a code is for us. The ICD-10 instruction manual makes a distinction between chapters, block of categories, three-character categories and four-character subcategories (which from now on we'll refer to as chapters, blocks, categories and subcategories), with a few additional five-character subcategories: we will consider all these items as codes.

Generally speaking, the codes of subcategories can be written in two different ways: with a dot (for example "I13.1") and without the dot (for example "I131"). The methods in this library can receive as input codes in both these formats. The codes returned by the functions will always be in the format with the dot. You can easily change the format of a code by using the removeDot and addDot functions.

Documentation

This library is comprised of a single class, ICD10CodesManipulator. When an object of this class is instantiated, it loads all the relevant data and creates the appropriate data structures to work effectively with it. It's through these objects that the functionalities of this library can be accessed.

ICD10CodesManipulator icd = new ICD10CodesManipulator();

ICD10CodesManipulator()

It creates a new ICD10CodesManipulator by loading and preparing the data of the ICD-10 classification.

ICD10CodesManipulator icd = new ICD10CodesManipulator();

boolean isValidItem(String code)

This method takes a string as input and returns true if the string is a valid chapter, block, category or subcategory in ICD-10, false otherwise.

Parameters:
code is the String that must be checked
Returns:
true if code is a valid ICD-10 code, otherwise false

icd.isValidItem("cat")
//false
icd.isValidItem("B99")
//true

boolean isCategoryOrSubcategory(String code)

This method takes a string as input and returns true if the string is a valid category or subcategory in ICD-10, false otherwise.

Parameters:
code is the String that must be checked
Returns:
true if code is a valid ICD-10 category or subcategory, otherwise false

icd.isCategoryOrSubcategory("A00-B99")
//false
icd.isCategoryOrSubcategory("B99")
//true

boolean isChapterOrBlock(String code)

This method takes a string as input and returns true if the string is a valid chapter or block in ICD-10, false otherwise.

Parameters:
code is the String that must be checked
Returns:
true if code is a valid ICD-10 chapter or block, otherwise false

icd.isChapterOrBlock("A00-B99")
//true
icd.isChapterOrBlock("B99")
//false

boolean isChapter(String code)

This method takes a string as input and returns true if the string is a valid chapter in ICD-10, false otherwise.

Parameters:
code is the String that must be checked
Returns:
true if code is a valid ICD-10 chapter, otherwise false

icd.isChapter("XII")
//true
icd.isChapter("B99")
//false

boolean isBlock(String code)

This method takes a string as input and returns true if the string is a valid block in ICD-10, false otherwise.

Parameters:
code is the String that must be checked
Returns:
true if code is a valid ICD-10 block, otherwise false

icd.isBlock("A00-B99")
//true
icd.isBlock("B99")
//false

boolean isCategory(String code)

This method takes a string as input and returns true if the string is a valid category in ICD-10, false otherwise.

Parameters:
code is the String that must be checked
Returns:
true if code is a valid ICD-10 category, otherwise false

icd.isCategory("B99")
//true
icd.isCategory("XIV")
//false

boolean isSubcategory(String code)

This method takes a string as input and returns true if the string is a valid subcategory in ICD-10, false otherwise.

Parameters:
code is the String that must be checked
Returns:
true if code is a valid ICD-10 subcategory, otherwise false

icd.isSubcategory("B95.1")
//true
icd.isSubcategory("B99")
//false

String getDescription(String code)

This method takes a string as input. If the string is a valid ICD-10 code, it returns a string with its short description, otherwise it throws an IllegalArgumentException.

Parameters:
code is an ICD-10 code
Returns:
the description of the code code
Throws:
IllegalArgumentException if code is not a valid ICD-10 code

icd.getDescription("XII")
//"Diseases of the skin and subcutaneous tissue"
icd.getDescription("F00")
//"Dementia in Alzheimer disease"

String getParent(String code)

This method takes a string as input. If the string is a valid ICD-10 code, it returns a string containing its parent, otherwise it throws an IllegalArgumentException. If the code doesn't have a parent (that is, if it's a chapter), it returns an empty string.

Parameters:
code is an ICD-10 code
Returns:
the parent of the code code
Throws:
IllegalArgumentException if code is not a valid ICD-10 code

icd.getParent("C00")
//"C00-C14"
icd.getParent ("XII")
//""

ArrayList<String> getChildren(String code)

This method takes a string as input. If the string is a valid ICD-10 code, it returns an ArrayList<String> containing its children, otherwise it throws an IllegalArgumentException. If the code doesn't have children, it returns an empty ArrayList<String>.

Parameters:
code is an ICD-10 code
Returns:
an ArrayList<String> containing the children of the code code
Throws:
IllegalArgumentException if code is not a valid ICD-10 code

icd.getChildren("XII")
//[L00-L08, L10-L14, L20-L30, L40-L45, L50-L54, L55-L59, L60-L75, L80-L99]
icd.getChildren("H60.1")
//[]

ArrayList<String> getAncestors(String code)

This method takes a string as input. If the string is a valid ICD-10 code, it returns an ArrayList<String> containing all its ancestors in the ICD-10 classification, otherwise it throws an IllegalArgumentException. The results are ordered from its parent to its most distant ancestor.

Parameters:
code is an ICD-10 code
Returns:
an ArrayList<String> containing the ancestors of the code code
Throws:
IllegalArgumentException if code is not a valid ICD-10 code

icd.getAncestors("H60.1")
//[H60, H60-H62, VIII]

ArrayList<String> getDescendants(String code)

This method takes a string as input. If the string is a valid ICD-10 code, it returns an ArrayList<String> containing all its descendants in the ICD-10 classification, otherwise it throws an IllegalArgumentException. The returned codes are ordered as in a pre-order depth-first traversal of the tree containing the ICD-10 classification.

Parameters:
code is an ICD-10 code
Returns:
an ArrayList<String> containing the descendants of the code code
Throws:
IllegalArgumentException if code is not a valid ICD-10 code

icd.getDescendants("C00")
//[C00.0, C00.1, C00.2, C00.3, C00.4, C00.5, C00.6, C00.8, C00.9]

boolean isAncestor(String a, String b)

This method takes two strings as input. If both strings are valid ICD-10 codes, it returns true if the first code is an ancestor of the second code. If at least one of the strings is not a valid ICD-10 code, it throws an IllegalArgumentException.

Parameters:
a is an ICD-10 code
b is an ICD-10 code
Returns:
true if a is one of the ancestors of b, false otherwise Throws:
IllegalArgumentException if a or b are not a valid ICD-10 code

icd.isAncestor("XVIII","R01.0")
//true
icd.isAncestor("K00-K14","M31")
//false

boolean isDescendant(String a, String b)

This method takes two strings as input. If both strings are valid ICD-10 codes, it returns true if the first code is a descendant of the second code. If at least one of the strings is not a valid ICD-10 code, it throws an IllegalArgumentException.

Parameters:
a is an ICD-10 code
b is an ICD-10 code
Returns:
true if a is one of the descendants of b, false otherwise Throws:
IllegalArgumentException if a or b are not a valid ICD-10 code

icd.isDescendant("R01.0","XVIII")
//true
icd.isDescendant("M31","K00-K14")
//false

String getNearestCommonAncestor(String a, String b)

This method takes two strings as input. If both strings are valid ICD-10 codes, it returns their nearest common ancestor if it exists, an empty string if it doesn't exist. If at least one of the strings is not a valid ICD-10 code, it throws an IllegalArgumentException.

Parameters:
a is an ICD-10 code
b is an ICD-10 code
Returns:
the nearest common ancestor of a and b if it exists, an empty string otherwise Throws:
IllegalArgumentException if a or b are not a valid ICD-10 code

icd.getNearestCommonAncestor("H28.0","H25.1")
//"H25-H28"
icd.getNearestCommonAncestor("K35","E21.0")
//""

boolean isLeaf(String code)

This method takes a string as input. If the string is a valid ICD-10 code, it returns true if the code is a leaf in the ICD-10 classification (that is, it has no descendants), false otherwise. If the string is not a valid ICD-10 code it throws an IllegalArgumentException.

Parameters:
code is an ICD-10 code
Returns:
true if code is a leaf in the ICD-10 classification, false otherwise Throws:
IllegalArgumentException if code is not a valid ICD-10 code

icd.isLeaf("H28")
//false
icd.isLeaf("H28.0")
//true
//""

ArrayList<String> getAllCodes(boolean withDots)

This method takes a boolean for input and returns an ArrayList<String> containing all the items in the ICD-10 classification. If 'withDots' is true, the subcategories in the ArrayList<String> will have a dot in them, if it's false the subcategories won't have a dot in them.

Parameters:
withDots is a boolean that controls whether the codes in the list that is returned are in the format with or without the dot.
Returns:
the list of all the codes in the ICD-10 classification, ordered as in a depth-first pre-order visit

icd.getAllCodes(true)
//[I, A00-A09, A00, A00.0, A00.1, A00.9, A01, A01.0, ...
icd.get_all_codes(false)
//[I, A00-A09, A00, A000, A001, A009, A01, A010, ...

ArrayList<String> getAllCodes()

This method takes a boolean for input and returns the list of all the items in the ICD-10 classification. The codes in the ArrayList<String> are in the format with the dot.

Returns:
the list of all the codes in the ICD-10 classification, ordered as in a depth-first pre-order visit

icd.getAllCodes()
//[I, A00-A09, A00, A00.0, A00.1, A00.9, A01, A01.0, ...

int getIndex(String code)

This method takes a string as input. If the string is a valid ICD-10 code, it returns its index in the list returned by getAllCodes, otherwise it throws an IllegalArgumentException.

Parameters:
code is an ICD-10 code
Returns:
the index of the code code in the list returned by getAllCodes Throws:
IllegalArgumentException if code is not a valid ICD-10 code

icd.getIndex("P00")
//7159
icd.getAllCodes(True).get(7159)
//"P00"

String removeDot(String code)

This method takes a string as input. If the string is a valid ICD-10 code, it returns the same code in the notation without the dot, otherwise it throws an IllegalArgumentException.

Parameters:
code is an ICD-10 code
Returns:
the same code in the format without the dot Throws:
IllegalArgumentException if code is not a valid ICD-10 code

icd.removeDot("H60.1")
//"H601"
icd.removeDot("H601")
//"H601"
icd.removeDot("G10-G14")
//"G10-G14"

String addDot(String code)

This method takes a string as input. If the string is a valid ICD-10 code, it returns the same code in the notation with the dot, otherwise it throws an IllegalArgumentException.

Parameters:
code is an ICD-10 code
Returns:
the same code in the format with the dot Throws:
IllegalArgumentException if code is not a valid ICD-10 code

icd.addDot("H60.1")
//"H60.1"
icd.addDot("H601")
//"H60.1"
icd.addDot("G10-G14")
//"G10-G14"

Conclusion

This is everything you needed to know before using the SimpleICD10 library - please contact me if you feel I missed something or there's some passage that you think should be explained better or more. Also contact me if you find any errors in the library or in the documentation.

If you are feeling generous, consider making a donation using one of the methods listed at the end of this document.

Stefano Travasci

Paypal:

Curecoin: BJdY5wCjN79bnq7jYLSowR7THzdm1CFDT9

Bitcoin: bc1qt5w3x89x546z5kwthu9hcyh5tcxr6rdf6t6uvr

_{let me know if your favorite donation method is not in this list}

StefanoTrv/SimpleICD10-Java-edition