Understanding the Basic Terminology

Report Definition

Report Definitions are the outermost layer of your report. They contain one or more DataSet Definitions which in turn will contain the data for your report.

DataSet Definition

A DataSet Definition maps out what information will be in your report. It will contain the data for your report or lower level components which themselves contain the data for your report. Row-Per-Patient reports are an example of the former whereas Cohort Indicator reports are an example of the latter. A Cohort Indicator DataSet Definition will have associated Indicators which will require underlying cohorts.

Cohort Query

Cohorts are the building blocks of an Indicator Report. They must be created before questions can be added to an Indicator Report. A cohort is a group of people who meet a certain condition or conditions. When one creates a Cohort Query, such as number of pediatric patients on ARVs, the result is a list of patients who meet those criteria (pediatric and on ARV).
Composition Cohorts\ combine multiple cohorts or give the inverse of one cohort.   For instance, you could have a cohort of people who weigh less than 30 KG and a cohort of people who have been enrolled in the program called HIV Program. You could create a Composition Cohort which returns people who are in the HIV Program and less than 30 KG. You could also return people who are in the HIV Program but not less than 30 KG. How you combine cohorts depends on which operators you select (using 'AND', 'OR', 'NOT').

Indicator

An Indicator requires a Cohort Query (so the underlying Cohort Query must be created before the Indicator). The reason? An Indicator aggregates the members of a cohort. You can't aggregate people in a group until the group has been created.
The most common form of aggregation is counting. An Indicator might count the cohort "Males" and return 521. An Indicator is not limited to counting, however. It is possible to apply other aggregate functions such as median, mean, and fractions as well as more complex logic expressions. For instance, you could create an Indicator for the mean cost of transport for a cohort of tuberculosis patients (providing you had already created the Numeric Cohort which has a question representing the numeric concept for transportation cost and already had a cohort of TB patients).

Dimension

A Dimension, like an Indicator, is built from a Cohort Query. A Dimension is a filter that narrows the results of an Indicator, removing the patients that don't meet the criteria of the Dimension
For instance, the question "Number of male pediatric patients on a first line regimen" might be made up of an Indicator that aggregates a Cohort of patients on first line regimens which has the Dimension of age and gender applied to it.
One could create a Composition Cohort Query that has everything in the Indicator (pediatric, male, and on first line) but Dimensions are helpful for reuse. For instance, in a report with a question about female adult ARV patients and female child ARV patients and male adult ARV patients and male child ARV patients, it is possible to create four complicated Indicators or, one could just create one Indicator, on ARVs and then create the appropriate Dimensions once each. These Dimensions would be applied to the Indicators as they are added to the report.

Filter

A Filter is also built from a Cohort Query. A Filter narrows the results of every question in the Report. For instance, applying a Filter using the Cohort Query "Not Exited from Care", makes sure that no patient ends up in a report that is no longer a patient of the clinic.

Renderers

Templates

Understanding Parameters vs. Fixed Values vs. Expressions

A report may have parameters associated with it. These parameters are available for use throughout the report. If the report has the parameters Start Date, End Date, and Location for instance, these values will be input at runtime and can be used by the underlying elements in the report. Not all elements will use any or all parameters. For instance, a cohort representing 'Females' needs no Start Date nor End Date (at least in our implementation).

From the other direction, a Cohort Query might have parameters or fixed values associated with it. For elements that will be reused, it makes sense to use parameters. For things that will be used only once or stay the same, it makes sense to use fixed values.

For instance, imagine having multiple questions asking the number of people who were in each program (HIV Program, TB Program, Heart Failure Program) at the End Date of a report. You could create one Cohort Query called 'InProgramOnDate' for instance. Here you would define the 'Programs' as a parameter called 'program' and the 'On the given date' section as a parameter called 'effectiveDate'. Then you could create several Indicators. Each one would have a fixed value for its program and a parameter for its effectiveDate which would tie that to the parameter endDate which would be defined in the Report Definition and passed in to the DataSet Definition which would then pass it in to the Indicator.

More explanation, especially about Expressions – TO BE ADDED

See Diagram. – TO BE ADDED
 
 

Restricting By Location

Locations are stored in different places depending on the implementation of OpenMRS.  The three most common are:

Last Encounter Location -- Use Encounter Query

Health Center -- Use Person Attribute Query

Program Location -- Currently not supported because this functionality is not widespread (only available in module form) until OpenMRS 1.8. 

Locations can be filtered at many different levels in the framework:

*Cohort Level

*Indicator Level

*Report Level

Types of Reports

Row-Per-Domain Object

Indicator-Based

Other

Period Indicator Reports have a special Period Indicator Report Definition that automatically comes with the parameters Start Date, End Date, and Location. The rest of the Reports are distinguished from each other not by their Report Definitions which are all the same basic type but rather by the Dataset Definitions which are associated with each report.

Types of DataSets

Row-Per-Domain Object DataSets

Simple Row Per Patient

 
A Simple Row Per Patient DataSet returns one row for each patient. Which details about a patient will be included in the report is set up in the corresponding Simple Patient Dataset. There are four different types of information which can be included in the Dataset:

• Person/Patient Properties- Examples of patient properties are Birthdate, Gender, GivenName, FamilyName, PatientID (internal), Dead. For a full list, see the OpenMRS API for the Patient object, for instance OpenMRS 1.6 API. Any method that starts with the word 'get' such as getBirthdate can be accessed simply by dropping the word 'get'.
• Person Attribute Types- Available attributes will appear in a dropdown. Depending on the implementation, this list might include such things as Health Center, Birthplace, Civil Status, etc.
• Identifier Types- Available identifiers will appear in a dropdown. This list includes any identifiers defined in a given implementation such as Social Security Number, Government ID, Health Program ID, etc.
• Program Workflow States- Workflow states will vary depending on implementation. Examples might include Treatment Status, Evaluation Status, Surgery Status, etc. Note that this returns the patient's current workflow state as of the day the report is run.
   

See Building a Simple-Row-Per-Report\ for step-by-step instructions to build this report from within OpenMRS or Building Reports for Developers\ for instruction on how to build reports inside a module.

Logic

Here is where the description will go.
 
 

Indicator-Based DataSets

Period Indicator

A Period Indicator DataSet is useful for monthly or quarterly Indicator Reports. That is, reports that have a list of questions with a count of people who meet each question's criteria. These reports have parameters of Start Date, End Date, and Location which are entered as the report is run to constrain the results to given time period and location. See Building an Indicator Report\ for step-by-step instructions to build this report from within OpenMRS or Building Reports for Developers\ for instruction on how to build reports inside a module.

Cohort Crosstab

Here is where the description will go.
 
 

Cohort Indicator with Dimensions

Here is where the description will go.
 
 

LINK TO Screen Shots

Other DataSets

Data Export

Here is where the description will go.
 
 

SQL

Here is where the description will go.
 
 

Types of Cohort Queries

Cohort Query Types By Domain

1. Concept: Concepts are defined and used to support strongly coded data throughout the system
2. Encounter: Contains the meta-data regarding health care providers interventions with a patient.

   Domain Object	Table	Field	Cohort Queries
   Encounter	encounter	encounter_type	Encounter Query
   Encounter	encounter	form_id	Encounter Query
   Encounter	encounter	location_id	Encounter Query
   Encounter	encounter	encounter_provider	FUTURE RELEASE?
   Encounter	encounter	encounter_datetime	Encounter Query
   Encounter	encounter	creator	Encounter Query
   Encounter	encounter	date_created	Encounter Query

3. Form: Essentially, the user interface description for the various components.
4. Observation: This is where the actual health care information is stored. There are many observations per Encounter.

   Domain Object	Table	Field	Cohort Queries
   Observation	obs	question	Coded Observation Query, Date Observation Query, Numeric Observation Query, Text Observation Query
   Observation	obs	obs_datetime	Coded Observation Query, Date Observation Query, Numeric Observation Query, Text Observation Query
   Observation	obs	location_id	Coded Observation Query, Date Observation Query, Numeric Observation Query, Text Observation Query
   Observation	obs	encounter_id	Coded Observation Query, Date Observation Query, Numeric Observation Query, Text Observation Query
   Observation	obs	value_coded	Coded Observation Query
   Observation	obs	value_datetime	Date Observation Query
   Observation	obs	value_numeric	Numeric Observation Query
   Observation	obs	value_text	Text Observation Query
   Observation	obs	value_boolean	Numeric Observation Query (using value EQUALS 0 or 1)

5. Order: Things/actions that have been requested to occur.

   Domain Object	Table	Field	Cohort Queries
   Drug Order	drug_order	drug_inventory_id	Drugs Active Query, Drugs Started Query, Drugs Completed Query
   Drug Order	order	start_date	Drugs Active Query, Drugs Started Query
   Drug Order	order	auto_expire_date	Drugs Active Query, Drugs Completed Query
   Drug Order	order	discontinued_date	Drugs Active Query, Drugs Completed Query

   NOTE-- Drug Order Queries have been removed from the core module. For now, create custom definitions and evaluators for drug orders. See module rwandareports for an example of this.
    

1. Patient: Basic information about patients in this system.
2. User: Basic information about the people that use this system.
3. Person: Basic information about person in the system.

   Domain Object	Table	Field	Cohort Queries
   Person	person	birthdate	Age Query, Birth and Death Query
   Person	person	gender	Gender Query
   Person Attribute	person_attribute	person_attribute_type	Person Attribute Query
   Relationship	relationship	relationship	FUTURE RELEASE?

4. Business: Non medical data used to administrate openmrs
5. Groups/Workflow: Workflows and Cohort data

   Patient Program	patient_program	program_id	Program Enrollment Query, In Program Query
   Patient Program	patient_program	date_enrolled	Program Enrollment Query, In Program Query
   Patient Program	patient_program	date_completed	Program Enrollment Query, In Program Query
   Patient State	patient_state	state	Patient State Query, In State Query
   Patient State	patient_state	start_date	Patient State Query, In State Query
   Patient State	patient_state	end_date	Patient State Query, In State Query

   
   

   Cohort Query Types Not Domain Related

Static Query
SQL Query
Inverse Query
 
 

Building Reports Inside OpenMRS (For Implementers)

IMAGE OF THREE REPORTS

There are three different options for building reports. The Period Indicator Report option as well as the Row-Per-Patient option are a shortcut method of building these particular reports. All reports are associated with one or more DataSet Definitions. The association with these two reports is done automatically whereas for the third option, Custom Report(Advanced), you create a Report Definition and a DataSet Definition and link them explicitly. For more information see Types of Reports.

In the two tutorials that follow, an example of one report built using the shortcut method, a Period Indicator Report, will be demonstrated. The second example will show a Custom Report in the form of a Simple Row-Per-Patient report where you will explicitly create and link the Report and DataSet Definition.

Building a Simple Row-Per-Patient Step-By-Step

This step-by-step tutorial will guide the user in the creation of a Row-Per-Patient Report, using a simple row-per-patient report as an example. It will show how to create the underlying dataset definition for the report as well the report itself.
 
See Row-Per-Domain Object Report Definition for details.
 
 

Create a report that includes patients and gives some information about them.

Needed components (Must be done in this order as the first items are building blocks for items thereafter):

Step 1. Build DataSet Definition\
 

Step 2. Build Report\
 

Step 2. Add DataSet to Report\
 
 

Create DataSet Definition

 

 

 
 

Create Report Definition

 

 

 

Add the DataSet Definition to the Report

 

 

 
 

Building Indicator Reports Step-By-Step

Period Indicator Report

This step-by-step tutorial will guide the user in the creation of indicator reports, using a Period Indicator Report as an example. It will show how to create the underlying components for the report as well as how to set up the first question.
 
See Indicator Report Definition for details.
 
 

Create a report that only includes people in the Heart Failure Program. Many questions will restrict by gender. The first question will be:  

* Percentage of men whose main job is farming.

Needed components (Must be done in this order as the first items are building blocks for items thereafter):

Step 1. Build Cohorts

• Males\
• Farmers\
• In Heart Failure Program\
   

Step 2. Build Indicators

• % Farmers\
   

Step 3. Build Dimension

• Males\
   

Step 4. Create Report

• Create Heart Failure Program Report\
   

Step 5. Add Filter

• Add In Heart Failure Program Filter\
   

Step 6. Add Dimension

• Add Male Dimension\

Step 7. Add Question

• Percentage of men whose main job is farming.\
   
   

Cohort Indicator with Dimensions Report

This step-by-step tutorial will guide the user in the creation of indicator reports, using a Cohort Indicator with Dimensions Report as an example. It will show how to create the underlying components for the report as well as how to set up the first question. This example will highlight how parameters are used in reports. See Understanding Parameters\ for details.
 
See Indicator Report Definition for details.
 
 

The first question will be:  

* People in the HIV Program at the endDate of the report.

Needed components (Must be done in this order as the first items are building blocks for items thereafter):

Step 1. Build Cohort

• In HIV Program\
   

Step 2. Build Indicator

• Number of People In HIV Program\
   

Step 3. Create Data Set Definition

• Create Indicator with Dimension DSD\
   
• Add Question (Indicator) to DSD\

Step 4. Create Report

• Create HIV Program Report\
   

Step 5. Add Data Set Definition to Report

• Add Indicator with Dimension DSD\
   
   

Building Indicator Report Components

Creating Cohort Queries

See Cohort Query Definition\.

 

 
 

Male Cohort--Returns all male patients.

 

 

 
 

Farmer Cohort--Returns all patients whose main activity is farming.

 

 
 

In Heart Failure Program Cohort--Returns all patients who are in the Heart Failure Program on a specific date.  You will set that date to be the End Date of the report in the indicator.  By using a parameter here, this cohort can be reused more easily. For instance, you could create two indicators, one which uses this cohort with the End Date of the report and one which uses this cohort with the Start Date of the report.

 

 

 
 

Heart Failure Form Cohort--Returns the patients who have any of the Heart Failure forms filled out.

 

 
 

In HIV Program Cohort--Returns the patients who in the HIV Program at the End Date of the report.
 

 

 
 

Transportation Cost Cohort--Returns the patients who have a transportation cost observation.

 
 

Health Center Location Cohort--Returns the patients who have been assigned a specific health center as a patient attribute.

 
 

Composition Cohorts

Composition Cohorts are a way to combine two or more cohorts or negate a single cohort. See Cohort Queries\.

Farmer and In Heart Failure Program Cohort--Returns all patients who both have the main activity of farming and are in the Heart Failure Program on a specific date.
 
 

Creating Cohort Indicators

See Indicator Definition\.

 

 

 
 

Farmer Indicator--Returns the percent patients in the Heart Failure Program at the report End Date whose main activity is farming and whose health center is set as the Location parameter passed into the report (at runtime).

 

You have to create cohorts for Health Center Location, Farmers, and In Heart Failure Program before you can create this indicator. You can't aggregate something you haven't created yet.
See Cohorts\ for step-by-step instructions.
 

 
NOTE--The cohort must have the word Location in the name in order to be used in the Location Filter.
 
 

 
NOTE--The numerator is automatically constrained by the denominator. This means that the numerator will only return members who are Farmers and also In Heart Failure Program.  
 
 
Notice that you have to put in the Start Date, End Date, and Location. The End Date parameter will be passed into the denominator cohort, In Heart Failure Program. The Start Date and Location are not used. 
The only reason to keep these two as parameters for your indicator is so that you can use this indicator in a Period Indicator Report (which requires all three parameters to be present). 

See Understanding Parameters\ for a quick overview of parameters use.
 
 

Transportation Cost Indicator--Returns the median cost of transport for the cohort of patients who have a cost of transport (in this case in Rwandan Francs).

 

 
NOTE--If you have any problems with the logic tokens not being recognized and the indicator preview failing, make sure that your logic tokens have been registered.
 
 

In HIV Program Indicator--Returns the number of patients in the HIV Program on the End Date of the report.
 

 

 
 

Creating Dimensions

See Dimension Definition\.

 

 


 

 
You have to create a Male Cohort before this option will show up in the Cohort Definition drop down here.
See Cohorts\ for step-by-step instructions.  Now create a Female Cohort Query and Add that to your dimension on your own.
 

Creating a Period Indicator Report

Setting Up a Period Indicator Report

Add Filter to Report

Add Dimension(s) to Report

Add Indicators (Questions) to Report

Running a Period Indicator Report

See Running a Period Indicator Report\.

 
 

Creating an Indicator with Dimensions Report

Create Data Set Definition

 

 

 
 

Add Question

 

 

 

 
 

Create Report

 

 
 

Add Data Set Definition

 

 

 

 

 
 

Running an Indicator with Dimension Report

See Running an Indicator with Dimension Report\.

 
 

Screen Casts Step-By-Step

To help get you started with the Reporting Module, we have put together a few screen casts.

• How to define a new Simple Report
• How to define a new Cohort Query with a parameter
• How to define a new Cohort Indicator (and map it to the underlying Cohort Query)
• How to break indicators down by dimensions like sex and age

Building Reports Inside Modules (For Developers)

Developing a Report Module

Getting Started with the basicreportmodule

IMPORTANT-- This module does not exist yet.  For now, see the following modules for ideas:

rwandareports

pihmalawi

mdrtb

Understanding and Extending the basicreportmodule

Custom Extension of the Reporting Framework

This release is our first stable release of the Reporting API. We have designed what we consider to be the basis for all of the APIs needed for the reporting. We feel very confident that the classes and interfaces designed will allow you to use and extend the API to:

• Define new cohort queries to allow users to calculate a custom metric that is specific to your organization.
• Define new data set definitions to expose data sets that are important to your users.
• Define new custom data set definitions that can be used in any implementation.
• Define a custom report based on your own data set definition.
• Build new reporting tools and user interfaces (e.g. a custom Reporting Dashboard for clinicians or an interactive data quality tool for data managers).
• Render reports in a standard format (e.g. SDMX-HD).
• Render reports in a proprietary format (e.g. .docx).
• Define custom logic rules to be used in indicators and cohort queries.
• Define new data quality rules to allow data managers to identify problems areas within your form entry process.

Using Parameters in SQL Cohort Queries

Pre-defined parameters:startDate, endDate, and location.
Self-defined parameters: you can include the parameters in sql queries by using the notation of :parameterName. For example, you can set up enrollment date by using :enrollmentDate in your sql statement. Remember to choose the correct data type. In this example, the data type should be date instead of string. If not, the program will treat it as a string instead of date. You won't get a date picker for this field as well. Also, those parameters cannot be part of the SELECT statement. Instead, they should be used in the WHERE clause.

Reporting Analysis

Running Reports Step-By-Step

If your Run a Report menu has no reports, then you will have to build a report first.  See Building Reports Inside OpenMRS\ or Building Reports for Developers\ for step-by-step instructions.

Web-Based Period Indicator Report

 

 

 

 

Excel-Based Period Indicator Report using a Template

Row-Per-Patient Report

 

 

 
 

Excel-Based Indicator with Dimensions Report

IMAGES GO HERE

Report History

Report History description here. 
 
IMAGES HERE

Indicators Over Time

Indicator description here. 
 
IMAGES HERE

Data Set Viewer

Data Set Viewer description here. 
 

 

Scheduling Reports

Scheduling description here.