=====================
API / Grouper
=====================

.. contents::
   :depth: 2
   :local:
   :backlinks: none

.. highlight:: java


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.