{"type":"doc","content":[{"type":"heading","attrs":{"level":2},"content":[{"text":"Overview","type":"text"}]},{"type":"paragraph","content":[{"text":"The Calculation module provides a framework for OpenMRS developers to author from simple to complex calculations to produce a particular piece of data for a single patient or a cohort of patients. It is a high level abstraction of rules/calculations, simple in that it provides a minimal number of useful concrete implementations of its core components that can be used out of the box but providing a much more flexible tool for authoring patient centered calculations.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Downloads","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Download the omod from the module repository: ","type":"text"},{"text":"https://addons.openmrs.org/#/show/org.openmrs.module.calculation","type":"text","marks":[{"type":"link","attrs":{"href":"https://addons.openmrs.org/#/show/org.openmrs.module.calculation"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"View/download the source code on github: ","type":"text"},{"text":"https://github.com/openmrs/openmrs-module-calculation","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/openmrs/openmrs-module-calculation"}}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Technical Overview","type":"text"}]},{"type":"paragraph","content":[{"text":"The module is designed around a couple of concepts described below:","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"PatientCalculation","type":"text"}]},{"type":"paragraph","content":[{"text":"A PatientCalculation represents a definition that can be evaluated to produce patient data. A PatientCalculation can expose parameters which control the results of its calculation. All calculations implement the super interface ","type":"text"},{"text":"Calculation","type":"text","marks":[{"type":"strong"}]},{"text":". It is highly recommended for calculations to extend BaseCalculation rather than directly implementing Calculation Interface.","type":"text"}]},{"type":"paragraph","content":[{"text":"The PatientCalculation interface exposes the method ","type":"text"},{"text":"getParameterDefinitionSet()","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" which should return a set of parameter definitions exposed by the calculation.","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"Calculations are stateful and non-singleton, therefore it is good practice to always get a new instance of the calculation from the CalculationProvider, if you wish to share certain information between calculations, use the PatientCalculationContext.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"The PatientCalculation interface exposes the method below:","type":"text"}]},{"type":"paragraph","content":[{"text":"evaluate(Collection cohort, Map parameterValues, PatientCalculationContext context)","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":": This where all the logic for the PatientCalculation goes.","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"Evaluate implementations must account on the fact that they may be executed by PatientCalculationService in manageable batches e.g. when the service is passed 10,000 patients, the evaluate method will be called 10 times and passed 1,000 patients each time.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Examples","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":":","type":"text"}]},{"type":"paragraph","content":[{"text":"HelloWorldCalculation.java","type":"text","marks":[{"type":"em"}]}]},{"type":"codeBlock","content":[{"text":"public class HelloWorldCalculation extends BaseCalculation implements PatientCalculation {\n\n @Override\n public CohortResult evaluate(Collection cohort, Map parameterValues, PatientCalculationContext context) {\n\n CohortResult results = new CohortResult();\n if (cohort != null) {\n PatientService ps = Context.getPatientService();\n for (Integer patientId : cohort) {\n Patient patient = ps.getPatient(patientId);\n if (patient != null) {\n results.put(patientId, new SimpleResult(\"Hello World from \" + patient.getPersonName().getFullName(),\n this, context));\n }\n }\n }\n\n return results;\n }\n}\n","type":"text"}]},{"type":"paragraph","content":[{"text":"HelloWorldConfigurableCalculation.java","type":"text","marks":[{"type":"em"}]}]},{"type":"codeBlock","content":[{"text":"public class HelloWorldCalculation extends BaseCalculation implements PatientCalculation, ConfigurableCalculation {\n //to be set via setConfiguration() method below\n\tprivate String name;\n\n\tpublic String getName() {\n\t\treturn name;\n\t}\n\n\tpublic void setName(String name) {\n\t\tthis.name = name;\n\t}\n\n\t@Override\n\tpublic void setConfiguration(String configuration) throws InvalidCalculationException {\n\t\tif (configuration == null)\n\t\t\tthrow new InvalidCalculationException(\"The name is required\");\n\t\tname = configuration;\n\t}\n\n\n @Override\n public CohortResult evaluate(Collection cohort, Map parameterValues, PatientCalculationContext context) {\n\n CohortResult results = new CohortResult();\n if (cohort != null) {\n PatientService ps = Context.getPatientService();\n for (Integer patientId : cohort) {\n Patient patient = ps.getPatient(patientId);\n if (patient != null) {\n results.put(patientId, new SimpleResult(\"Hello World from \" + patient.getPersonName().getFullName(),\n this, context));\n }\n }\n }\n\n return results;\n }\n}\n","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"CalculationProvider","type":"text"}]},{"type":"paragraph","content":[{"text":"A CalculationProvider is responsible for retrieving a Calculation instance given a calculation name and an optional configuration string.","type":"text"}]},{"type":"paragraph","content":[{"text":"Note","type":"text","marks":[{"type":"strong"}]},{"text":": CalculationProviders have to be registered as spring beans so as to be found by the framework. A calculationProvider should typically invoke the setConfiguration() method of the calculation instance before returning it in case it is a subclass of a ConfigurableCalculation. The module comes with a ","type":"text"},{"text":"ClasspathCalculationProvider","type":"text","marks":[{"type":"strong"}]},{"text":" that can return a Calculation given its fully qualified class name and is on the classpath, its is limited to Calculations that have constructors that require no arguments. ","type":"text"}]},{"type":"paragraph","content":[{"text":"A typical implementation for a calculation provider would be such that the calculationName is the calculation class to instantiate and configuration represents the serialized property values that need to be configured on this calculation instance, however, it is totally up to the Provider to define this. For example, to retrieve the Calculation for \"Most Recent Weight\":","type":"text"}]},{"type":"codeBlock","content":[{"text":"Calculation Name: org.openmrs.calculation.definition.MostRecentObsCalculation\nConfiguration: concept=","type":"text"}]},{"type":"paragraph","content":[{"text":"There would then be a ","type":"text"},{"text":"CalculationProvider","type":"text","marks":[{"type":"code"}]},{"text":" registered to handle this type of Calculation which would know it needed to first instantiate a new instance of ","type":"text"},{"text":"MostRecentObsCalculation","type":"text","marks":[{"type":"code"}]},{"text":", configure its properties via the parsed values from the configuration string, and then return the configured Calculation instance. ","type":"text"},{"text":"CalculationProvider","type":"text","marks":[{"type":"code"}]},{"text":"s will likely be wired to Calculation classes either via a registry or via annotations.","type":"text"},{"type":"hardBreak"},{"text":" A CalculationProvider is responsible for retrieving a Calculation instance given a calculation name and an optional configuration string. A typical implementation would be such that Calculation name is the Calculation class to instantiate or just a logical name that uniquely identifies a single Calculation from all the provider provides and the configuration represents the serialized property values that need to be configured on this Calculation instance, however it is totally up to the Provider to define this. For example, to retrieve the Calculation for \"Most Recent Weight\":","type":"text"}]},{"type":"codeBlock","content":[{"text":"Calculation Name: org.openmrs.calculation.definition.MostRecentObsCalculation\nConfiguration: concept=","type":"text"}]},{"type":"paragraph","content":[{"text":"There would then be a calculation provider registered to handle this type of calculation which would know how to create a new instance of MostRecentObsCalculation, configure its properties via the parsed values from the configuration string, and then return the configured Calculation instance.","type":"text"}]},{"type":"paragraph","content":[{"text":"Example","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":": TestCalculationProvider.java (This could be registered as a spring bean)","type":"text","marks":[{"type":"em"}]}]},{"type":"codeBlock","attrs":{"language":"java"},"content":[{"text":"public class TestCalculationProvider implements CalculationProvider {\n //Just for testing purposes, this provider has an in-memory source of calculations in form of a map, \n //typically it should be from anywhere known by the provider e.g from the DB\n\tprivate Map> calculations = new HashMap>();\n\n\tpublic TestCalculationProvider() {\n\t\t//This could be map of fully qualified/unique logical names and Classes\n\t\tcalculations.put(\"HelloWorldCalculation\", HelloWorldCalculation.class);\n\t}\n\n\t@Override\n\tpublic Calculation getCalculation(String calculationName, String configuration) {\n\n\t\tif (calculationName != null) {\n\t\t\tClass clazz = calculations.get(calculationName);\n\t\t\tif (clazz != null) {\n\t\t\t\ttry {\n\t\t\t\t\tCalculation calculation = clazz.newInstance();\n\t\t\t\t\tif (StringUtils.isNotBlank(configuration)) {\n\t\t\t\t\t\t//do further initialization...............\n\t\t\t\t\t}\n\n\t\t\t\t\treturn calculation;\n\t\t\t\t}\n\t\t\t\tcatch (Exception e) {}\n\t\t\t}\n\n // If this is a ConfigurableCalculation, try to configure it\n\t\t if (calculation instanceof ConfigurableCalculation) {\n\t\t\t ((ConfigurableCalculation)calculation).setConfiguration(configuration);\n\t\t }\n\t\t // If this is not a ConfigurableCalculation, but a configuration was passed in, throw an Exception\n\t\t else {\n\t\t\t if (StringUtils.isNotBlank(configuration)) {\n\t\t\t throw new InvalidCalculationException(this, calculationName, configuration);\n\t\t\t }\n\t\t }\n\t\t}\n\n\t\treturn null;\n\t}\n}\n","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"CalculationResult","type":"text"}]},{"type":"paragraph","content":[{"text":"A ","type":"text"},{"text":"CalculationResult","type":"text","marks":[{"type":"code"}]},{"text":" is the data that is produced from evaluating a Calculation for a single patient. CalculationResults are strongly typed but provide a convenient method for casting to other appropriate datatypes. The module provides a ","type":"text"},{"text":"SimpleResult","type":"text","marks":[{"type":"strong"}]},{"text":" that can be used out of the box though one could extend it to add extra features. There is also a ","type":"text"},{"text":"DateBaseResult","type":"text","marks":[{"type":"strong"}]},{"text":" interface that can be implemented for domain objects that have a date of occurrence e.g Encounter has encounterDatetime. The module ships with the following date based results; ","type":"text"},{"text":"EncounterResult","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"ObsResult","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"ParameterDefinition","type":"text"}]},{"type":"paragraph","content":[{"text":"This is an abstraction of the parameters that a calculation exposes, they encapsulate information about the values against which a calculation can be evaluated. These can be optional or required. All parameter definitions should extend the class ParameterDefinitionSet which is technically a wrapper for a HashSet.","type":"text"}]},{"type":"paragraph","content":[{"text":"Say you have a Calculation that requires some sort of user input e.g An AgeCalculation that requires the user to specify the units in which to express the patient age i.e. months Vs years, a ","type":"text"},{"text":"ParameterDefinition","type":"text","marks":[{"type":"code"}]},{"text":" could be useful to encapsulate certain attributes. For instance, to specify whether it is ","type":"text"},{"text":"required","type":"text","marks":[{"type":"strong"}]},{"text":", the ","type":"text"},{"text":"datatype","type":"text","marks":[{"type":"strong"}]},{"text":" of the allowed values plus the ","type":"text"},{"text":"name","type":"text","marks":[{"type":"strong"}]},{"text":" and ","type":"text"},{"text":"description","type":"text","marks":[{"type":"strong"}]},{"text":" to display in the user for the user. The ","type":"text"},{"text":"key","type":"text","marks":[{"type":"strong"}]},{"text":" property is intended to be used only programmatically.","type":"text"}]},{"type":"paragraph","content":[{"text":"The module comes with ","type":"text"},{"text":"SimpleParameterDefinition","type":"text","marks":[{"type":"strong"}]},{"text":" as the basic implementation of the interface and should be good enough for most use cases.","type":"text"}]},{"type":"paragraph","content":[{"text":"You can add parameters by calling:","type":"text"}]},{"type":"codeBlock","content":[{"text":"myAgeCalculation.addParameterDefinition(new SimpleParameterDefinition(\"units\", \"java.lang.String\", \"Months\", true));\n","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"PatientCalculationContext","type":"text"}]},{"type":"paragraph","content":[{"text":"The CalculationContext contains any contextual information that may be shared across one or more Calculation evaluations. This includes the date to base on when evaluating the calculation and a cache for storing the results for previously evaluated calculations. It should essentially replace any call for \"new Date()\" in evaluation code. To can create your own CalculationContext class by implementing the interface CalculationContext.","type":"text"}]},{"type":"paragraph","content":[{"text":"To obtain a PatientCalculationContext instance, call PatientCalculationService.createCalculationContext()","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"How it all comes together","type":"text"}]},{"type":"paragraph","content":[{"text":"First you need an instance of a CalculationProvider, query the provider for the calculation you are interested in. There are 2 ways to evaluate a calculation as shown below:","type":"text"}]},{"type":"paragraph","content":[{"text":"1. Calling the evaluate method of the calculation instance","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Example:","type":"text","marks":[{"type":"em"}]}]},{"type":"codeBlock","content":[{"text":"PatientCalculation calculation = (PatientCalculation)new TestCalculationProvider().getCalculation(\n\t\t\"HelloWorldCalculation\", null);\n Collection cohort = new ArrayList();\n cohort.add(6);\n cohort.add(7);\n CohortResult result = calculation.evaluate(cohort, null, null);//you can specify parameter values and a CalculationContext\n\n for (Map.Entry entry : cohortResult.entrySet()) {\n System.out.println(\"Patient with id:\"+entry.getKey()+\" says \" +entry.getValue().asType(String.class));\n }\n\n}\n","type":"text"}]},{"type":"paragraph","content":[{"text":"2. Using the PatientCalculationService ","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"By calling one of the evaluate methods in the PatientCalculationService, the evaluate method in the calculation service is overloaded. You can call the appropriate method and you have to specify the patient or cohort of patients, a calculation, an optional map of parameter values and a PatientCalculationContext. This is the recommended way to evaluate a calculation because the service does the extra job of enforcing the required parameters and parameter datatypes. It provides convenience methods for performing evaluations for a single patient, creates the CalculationContext under the hood if none is provided and also performs batch processing for cohorts of more than 1000 members","type":"text"}]},{"type":"paragraph","content":[{"text":"Example:","type":"text","marks":[{"type":"em"}]}]},{"type":"codeBlock","attrs":{"language":"java"},"content":[{"text":"public void sayHelloWorld() {\n\tPatientCalculation calculation = (PatientCalculation)new TestCalculationProvider().getCalculation(\n\t\t\"HelloWorldCalculation\", null);\n\tCollection cohort = new ArrayList();\n\tcohort.add(6);\n\tcohort.add(7);\n\tCohortResult cohortResult = Context.getService(PatientCalculationService.class).evaluate(cohort, calculation);\n\n\tfor (Map.Entry entry : cohortResult.entrySet()) {\n\t\tSystem.out.println(\"Patient with id:\"+entry.getKey()+\" says \" +entry.getValue().asType(String.class));\n\t}\n}\n","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"About TokenRegistrations","type":"text"}]},{"type":"paragraph","content":[{"text":"A TokenRegistration represents a saved Calculation instance in the database, and includes a unique name, the CalculationProvider, the calculationName, and the configuration for the calculation. The intention is to allow a fully configured Calculation instance to be retrieved given a unique name String. ","type":"text"}]},{"type":"paragraph","content":[{"text":"Example","type":"text","marks":[{"type":"strong"}]},{"text":": Getting a Calculation instance of a TokenRegistration, assuming you have a saved token","type":"text"}]},{"type":"codeBlock","attrs":{"language":"java"},"content":[{"text":"TokenRegistrationService service = Context.getService(TokenRegistrationService.class);\nMySavedCalculation calculation = service.getCalculation(myTokenName, MySavedCalculation.class);\n","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Release Notes","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"1.0 (Latest major release) - rev.29203","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Download module ","type":"text"},{"text":"here","type":"text","marks":[{"type":"link","attrs":{"href":"https://addons.openmrs.org/#/show/org.openmrs.module.calculation"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Changes since 0.9 ","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"CALC-38","type":"text","marks":[{"type":"link","attrs":{"href":"https://tickets.openmrs.org/browse/CALC-38"}}]},{"text":" - PatientCalculation.evaluate method should take a Collection instead of a Cohort","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"CALC-32","type":"text","marks":[{"type":"link","attrs":{"href":"https://tickets.openmrs.org/browse/CALC-32"}}]},{"text":" - Made change to clear the token cache on save and delete so that it gets rebuild","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"CALC-39","type":"text","marks":[{"type":"link","attrs":{"href":"https://tickets.openmrs.org/browse/CALC-39"}}]},{"text":" - Rename CohortResult to CalculationResultMap","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"CALC-41","type":"text","marks":[{"type":"link","attrs":{"href":"https://tickets.openmrs.org/browse/CALC-41"}}]},{"text":" - Calculation maven artifacts have a non-standard groupId","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"CALC-44","type":"text","marks":[{"type":"link","attrs":{"href":"https://tickets.openmrs.org/browse/CALC-44"}}]},{"text":" - ListResults should have a getValues() method","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"CALC-45","type":"text","marks":[{"type":"link","attrs":{"href":"https://tickets.openmrs.org/browse/CALC-45"}}]},{"text":" - ListResult should refer to Calculation and CalculationContext, not their Patient variants","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"CALC-43","type":"text","marks":[{"type":"link","attrs":{"href":"https://tickets.openmrs.org/browse/CALC-43"}}]},{"text":" - ResultUtil.convert and CalculationUtil.cast do not correctly convert things to Boolean","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"CALC-46","type":"text","marks":[{"type":"link","attrs":{"href":"https://tickets.openmrs.org/browse/CALC-46"}}]},{"text":" - Utility methods on CalculationResultMap for getting results as boolean or isEmpty without needing null tes","type":"text"}]}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"0.9 (RC)","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Got everything working taking into consideration all use cases and design described ","type":"text"},{"text":"here","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/display/docs/Logic+2.0+Design"}}]}]}]}]}]}]}],"version":1}

Browser not supported