API / Grouper

Usage

Obtain a classification system from file (provided JSON specifications, e.g. Version 1.1 for data year 2026 in this example)

import java.io.File;

import ch.oaat_otma.grouper.ClassificationSystemReader;
import ch.oaat_otma.grouper.PatientClassificationSystem;
import ch.oaat_otma.grouper.PCSError;

/* load a patient classification system from file. */
File pcsFile = new File("path/to/systems/system_ambP_XX_lkaat.json");
ClassificationSystemReader reader = new ClassificationSystemReader();
PatientClassificationSystem pcs = reader.readFromFile(pcsFile);

/* optionally check integrity of the system. */
List<PCSError> errors = pcs.check();
assert (errors.size() == 0);

Group a patient case and print the resulting group.

import ch.oaat_otma.grouper.Diagnosis;
import ch.oaat_otma.grouper.GrouperDecision;
import ch.oaat_otma.grouper.PatientCase;
import ch.oaat_otma.grouper.Service;

/* group a patient case. */
PatientCase pc = new PatientCase();
pc.setAgeYears(12);
Diagnosis d = new Diagnosis("R59.0");
pc.setDiagnosis(d);
Service s = new Service("C02.CP.0100", Side.L, 1, LocalDate.now(), 1);
pc.addService(s);
List<GrouperDecision> decPath = pcs.evaluate(pc);
System.out.println(pc.getGrouperResult().group);

/* was the service used for grouping. */
boolean used = s.isUsed();
System.out.println("Service " + s.code + " was used for grouping: " + used);
/* was the diagnosis used for grouping. */
used = d.isUsed();
System.out.println("Diagnosis " + d.code + " was used for grouping: " + used);

/** print the decision path */
for (GrouperDecision decision : decPath) {
    System.out.println(decision);
}

PatientClassificationSystem

The patient classification system object represents a classification system, e.g a specific version of the tariff system. The usual way to obtain a system is by parsing a provided specification file (single JSON file containing all logic, variables and tables.) using a ClassificationSystemReader. See example code above.

Common methods of PatientClassificationSystem:

/**
 * group a patient case with the provided patient case. Returns the decision path,
 * a decision for each node the patient case passes. The grouper result can be found in
 * pc.getGrouperResult(). Hence the provided patient case is changed. Use
 * #evaluateByValue(PatientCase) in order to avoid side effects.
 */
List<GrouperDecision> decPath = pcs.evaluate(pc);

/**
 * Obtain the grouper hash.
 * A 40 character long hex hash value representing all relevant data pertinent to
 * grouping. Classification systems with the same hash are guaranteed to result
 * in the same group results for the same input.
 * This can be used as an ID or to check for equality.
 */
String grouperHash = pcs.getGrouperHash();

/**
 * Get a list of all variables used in this system with their corresponding type.
 * There can be aliases which point to the same variable. E.g. ID, id, key,
 * case_number are all the same variable.
 */
Map<String, ExpressionType> usedVariables = pcs.getVariables();

Most other methods are called by a ClassificationSystemReader and can be ignored or are hidden in the setting of reading and executing the classification systems.

Catalog / obtaining tax points

A flat rate catalog can be read and applied to a group that resulted from grouping a patient case:

import ch.oaat_otma.grouper.Catalog;

File catalogFile = new File("path/to/systems/catalog_ambP_XX.csv");
Catalog catalog = Catalog.readFromFile(catalogFile);

/*
 * In order to avoid rounding issues / inaccuracies all tax point values are
 * represented as integer values as e^2 and need to be converted back (e.g 20323 > 203.23).
 * "C00.04B" is an example group as obtained after grouping a
 * patient case by pc.getGrouperResult().group.
 */
assert(40542 == catalog.getTaxPoints("C00.04B"));

The catalog CSV will bundled together with the patient classification system JSON specifications.