=====================
API / common classes
=====================

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

.. highlight:: java

The API
-------
Use the API / tarifmatcher library if you want to integrate the software in your own Java / JVM project. The library is
provided as a JAR file.
The public API for the tarifmatcher can be found in the package ch.oaat_otma for common classes and in its subpackages
for the respective components: grouper, mapper, casemaster.
All other packages and subpackages are not considered public and will therefore not be completely documented. Classes are subject to non-backwards compatible changes in their interfaces.


PatientCase
-----------
A patient case represents an outpatient treatment (ambulante Behandlung / traitement ambulatoire) in the context of outpatient
medical tariffs. The definition of a patient case / treatment is considered to be a single completed case with the case
definition according to annex B of the tariff structure contract already applied.

A patient case contains the following fields:

* ID
* Entry date (can also be calculated from birth date and age_years or from service dates using PatientCase#calculateAge())
* Birth date (can also be calculated from entry date and age_years using PatientCase#calculateAge())
* Age (can also be calculated from birth date and entry date using PatientCase#calculateAge())

    * Years
    * Days
    * Months
* Sex (M/W)
* Diagnosis (ICD10 or Tessinercode)
* Services (LKAAT)

    * Code
    * Side
    * Number
    * Date
    * Session number
* Tariff Positions (Tarpos, including drugs with GTIN tariff 402)

    * Code
    * Tariff code
    * Number
    * Date
    * Side
    * Reimbursed Amount (in CHF)
    * Session number
* Drugs (with ATC code, format and valid values are specified in more detail on the :doc:`drugs` page)

   * ATC code
   * Annex
   * Application
   * Dose
   * Unit
   * Date
   * Session number

Most fields of objects of type Code (Diagnosis, Service, Tarpo, Drug) are considered to be immutable (final). This includes all fields that are pertinent for the Casemaster, grouping and mapping.
Non immutable fields can be set and changed after the object is created. This includes an optional ID (used to identify the code in integrating systems like ERP, KIS, PIS, etc., unused by the Tarifmatcher.) and dynamically assigned values such as referenceService in Service or amount in Tapo.


.. attention::

   A patient case can have many fields that are not relevant for grouping in the context of certain patient classification systems. (e.g. secondary diagnoses, services in simulation systems, ..). All variables relevant for grouping for a certain classification system can be obtained by PatientClassificationSystem#getVariables()

Creating patient cases:

::

   PatientCase pc = new PatientCase();
   /* set an arbitrary ID / case number / PID. */
   pc.setId("1337");
   pc.setEntryDate(SharedUtils.parseDate("20250130"));
   pc.setAgeYears(65);
   pc.setAgeDays(0);
   pc.setBirthDate(SharedUtils.parseDate("20000101"));
   pc.setSex("M");
   pc.setDiagnosis(new Diagnosis("R59.0"));
   /* Add service / LKAAT codes (starting with data year 2026.) */
   pc.addService(new Service("C02.CP.0100"));
   /* or with side, number and date. */
   pc.addService(new Service("C02.CP.0100", Side.L, 1, LocalDate.now(), 1));
   /*
   * Add tariff position (Tarmed, tariff code '001', or other outpatient tariffs).
   * Relevant for simulation grouping up until data year 2025.
   */
   pc.addTarpo(new Tarpo("00.0010:1:001:14.0:20230130"));
   /* or with tariff code, number, date and reimbursed amount. */
   pc.addTarpo(new Tarpo("00.0010", "001", 1, LocalDate.now(), 14));


Copying a patient case:

::

   PatientCase original = new PatientCase();
   /* This copies only the input data and not grouper results. */
   PatientCase copy = new PatientCase(original);


Session
-------

A session represents a session or a patient contact. It contains all the services and tariff positions that were performed in a session or are attributed to a session.

A session contains the following fields:

* Session number
* Date
* Garant
* Diagnosis (ICD10 or Tessinercode)
* Capitulum (Capitulum / diagnosis group as assigned by the Casemaster)
* Services (sub attributes see PatientCase)
* Tariff Positions (Tarpos) (sub attributes see PatientCase)
* Drugs (with ATC code) (sub attributes see PatientCase)


Patient
-------

A patient represents all services performed within a given time on a given patient by a given provider. It is a list of sessions and the patient's master data.

A patient contains the following fields:

* Patient ID
* Birth date
* Sex
* Sessions (sub attributes see Session)


Serialization / Deserialization
-------------------------------

Besides Java serialization, the tarifmatcher library provides the following methods for serialization / deserialization:

**JSON serialization / deserialization:**

JSON serialization can also be used for other classes, for instance a mapper result. All fields are serialized.
This is the preferred method for networked single / few case applications.

::

   import ch.oaat_otma.grouper.pcencoders.JsonPatientCaseEncoder;
   import ch.oaat_otma.grouper.pcparsers.JsonPatientCaseParser;

   PatientCase pc = new PatientCase();
   pc.setId("1337");
   JsonPatientCaseEncoder encoder = new JsonPatientCaseEncoder();
   String json = encoder.encode(pc);

   JsonPatientCaseParser parser = new JsonPatientCaseParser();
   PatientCase decoded = parser.parse(json);

**Dynamic CSV serialization / deserialization:**

This format is used in the batchgrouper and the online batchgrouper: https://tarifmatcher.oaat-otma.ch. It is a CSV format with a header
delimited by semicolons and is much more compact than JSON.

::

   import ch.oaat_otma.grouper.pcencoders.DynamicPatientCaseEncoder;
   import ch.oaat_otma.grouper.pcparsers.DynamicPatientCaseParser;

   PatientCase pc = new PatientCase();
   pc.setId("1337");

   /** manually configure the variables you want to serialize / deserialize. */
   List<String> header = new ArrayList<String>() {
      {
            add("key");
            add("age");
            add("sex");
            add("diagnoses");
            add("tarpos");
            add("services");
      }
   };
   DynamicPatientCaseEncoder encoder = new DynamicPatientCaseEncoder(header);
   String headerLine = encoder.encodeHeader();
   String patientCaseLine = encoder.encode(pc);

   /** .. write to CSV file with a header line and N patient case lines .. */

   /** .. read from CSV file .. */

   DynamicPatientCaseParser parser = new DynamicPatientCaseParser();
   parser.convertHeader(headerLine);
   PatientCase decoded = parser.parse(patientCaseLine);


Thread-Safety
-------------

The usage of Casemaster.apply(), PatientClassificationSystem.evaluate() and Mapper.map() is thread-safe regarding the respective objects (Casemaster, PatientClassificationSystem and Mapper) but not their arguments: PatientCase.
Use PatientClassificationSystem.evaluateByValue() and Mapper.mapByValue() if you need thread-safety on the level of the patient case.
Hence Casemaster, PatientClassificationSystem and Mapper can be shared between threads, but the PatientCase objects must not be shared between threads.
The same applies to the serialization / deserialization classes. They are thread-safe regarding the respective objects (JsonPatientCaseEncoder, JsonPatientCaseParser, DynamicPatientCaseEncoder, DynamicPatientCaseParser) but not their arguments: PatientCase.