• About
• HNQIS 2.0 Setup
  • Metadata Requirements
    • Package Components
  • Set up HNQIS 2.0 using the Program Config App
    • Setup Process
• Scoring in HNQIS 2.0
  • Calculating a Score Containing Only Questions
  • Calculating a Score Containing Multiple Sub-scores
  • Calculating the Assessment Score
    • Calculating the Critical and Non-critical Scores
  • Scoring Limitations
    • Combining Scores and Questions
    • Leaving Gaps in the Feedback Order
• Competency Classes in HNQIS 2.0
• Set Up Button Metadata Generation
  • Scores Check
  • Assessment Questions Check
  • New Metadata Construction
  • Old Metadata Deletion
  • New Metadata Import
• Local Analytics
• FAQ

This manual details the way that DHIS2 tracker features are used to implement the various concepts in HNQIS. It covers the standardized metadata (Options sets, Data ELements, Tracker Attribute and System Attributes) that the data models uses, as well as how scores and other classifications are calculated. This documentation is directed to administrators that provide support or participate in the checklists configuration process, and are looking to understand the background processes that make HNQIS 2.0 work.

The Program Config App (PCA) allows for an easy and simple way of managing HNQIS Checklist. Currently the PCA is able to install the Metadata required in the DHIS2 server instance, as well as validate and generate HNQIS 2.0 specific metadata.

Go to the top

HNQIS 2.0 requires varios standardized DHIS2 options, data elements, attributes and other objects so a HNQIS checklist can be run on a given DHIS2 instance. The required metadata is either included on a HNQIS 2 export created on another server, or installed by the PCA (Program Configuration APP) - the dedicated DHIS2 web-app that allow you to configure HNQIS checklist. The Program Config App will enable H2 functionality only if the necessary Metadata required has been installed in the server. The necessary metadata package can installed from the PCA itself - see how to install it here.

IMPORTANT: If one or more components of the minimum required Metadata Package are missing from the server, some HNQIS 2.0 features will be automatically disabled until the files are installed/restored.

The PCA includes a Metadata Package with the minimum required Metadata, as well as some other components that are required while creating HNQIS checklists. Each component of the Metadata Package is detailed below:

NOTE:

• Some components are part of the minimum required Metadata Package, those are highlighted by an asterisk (*).
• The Program Rules mentioned are generated automatically using the Set Up Program button of the PCA when in HNQIS Mode.

Go to the top

To ensure the integrity of the HNQIS Metadata Package in the DHIS2 server, the PCA includes a Metadata Checker that also allows for quick repairs in case the Metadata is somehow damaged or lost.

This install/repair option basically performs an import with Replace strategy of all the metadata described in the previous section.

To set up HNQIS 2.0 while using the PCA first you have to load the app in the Programs Listing and then open the Settings Menu.

Settings Menu visible from the Programs Listing in the PCA.

To access the Metadata Checker click on the HNQIS 2.0 Status option. This will open a pop-up window detailing the current status of the HNQIS 2.0 Metadata Package in the server.

HNQIS 2.0 status window displaying that the Metadata Package is not installed.

In this case, the Metadata Package is not available in the server so it must be installed by clicking the Install Metadata button. Doing so will start the installation process which, once completed, will change the information displayed in the window.

HNQIS 2.0 Metadata Package successful installation.

Naturally, this requires some degree of permissions due to the interaction with various Metadata Objects. The required authorities for this action would be the following:

• Option Sets Add/Update Public
• Attributes Add/Update Public
• Data Elements Add/Update Public
• User Groups Add/Update Public
• Legend Sets Add/Update Public
• Tracked Entity Add/Update Public
• Tracked Entity Attribute Add/Update Public

Lacking any of those authorities will prevent the installation process from completing and will display errors according to the user's permissions.

Errors displayed when installing the HNQIS 2.0 Metadata with a user that lacks the required authorities.

If the HNQIS 2.0 Metadata Package has been installed but somehow any of its contents are lost or damaged, a message will be displayed indicating that the Metadata is incomplete.

Error displayed when the Minimum Metadata Package is incomplete or damaged.

This will also disable the option to create HNQIS 2.0 Programs from the Add Program button and also will prevent access to any HNQIS 2.0 Programs in the server.

New HNQIS 2.0 Program option disabled due to the incomplete Minimum Metadata Package.

Message displayed when accessing a HNQIS 2.0 Program while the Minimum Metadata Package is incomplete or out of date.

This error can be fixed by reinstalling the Metadata Package using the Install Metadata button in the HNQIS 2.0 Status window.

Go to the top

Assessment scores in HNQIS are calculated using a weighted arithmetic mean of all the answered questions grouped by Compositive Indicators (Also referred as Feedback Orders). The basic formula for the score in a section is the following:

The formula is applied for every score and its nested sub-scores. To explain this further let's create the structure of an example HNQIS 2.0 Checklist.

Example HNQIS 2.0 Checklist with multiple nested scores. Q means Question.

In HNQIS 2.0 you're able to nest scores inside other scores and even combine those nested scores, let's proceed to explain how every score is calculated. You can see that the scoring follows a hierarchy based on how the Assessment is structured, the most important part here is that scores formulas are defined from the lowest level of the hierarchy to the top (from the innermost part of the Assessment Tree to the exterior).

Assessment Tree: Name of the structure of the Assessment, it's called Tree because the branching structure resembles a tree.

This means that, in the given example, the first score formulas that will be defined are Score 1.1, Score 1.2, Score 2.1 and Score 3. Also, every score is split in two parts: Numerator and Denominator. This is due to the following reason.

You may think that Score 1 is calculated by performing an average of Score 1.1 and Score 1.2, but that's not the case. All of the scores are only defined by the questions contained in each score. So, in this case, the value of Score 1 is determined solely by applying the Scoring Formula to questions Q1, Q2, Q3, Q4, Q5, Q6 and Q7; ignoring the independent values of Score 1.1 and Score 1.2.

This is the reason why every score is split between Numerator and Denominator, so that those values can be re-used in the Scoring Formulas of the upper scores.

Go to the top

Let's use the Scoring Formula to define the values of Score 1.1 and Score 1.2, which contain only questions:

NOTE: To simplify this example, every question will have a Numerator and Denominator value of 2.

Splitting the main Scoring Formula in the Numerator and Denominator formulas results in the following set of formulas:

About the Numerator and Denominator

In reality, both the Numerator and Denominator are also split in two parts: Critical and Non-critical. The sum of Critical Numerator and Non-critical Numerator equals the Numerator of the score, the same applies for the Denominator of the score. This separation of Critical and Non-critical is mainly used for the Assessment Score and the Competency Class calculations, every other score uses the combination of Critical and Non-critical questions.

The use of this distinction will be further explained in the Calculating the Critical and Non-critical Scores section.

In this example we will assume that every question is Critical.

Now, the Score 1.1 which contains questions Q1, Q2 and Q3 would have the following set of formulas:

For Score 1.2 containing questions Q4, Q5, Q6 and Q7 the set of formulas would be the following:

The same process would be repeated for Score 2.1 and Score 3, that also only contains questions.

Go to the top

In order to define the value of Score 1, which contains multiple sub-scores, the Numerators and Denominators of each sub-score are used instead of calculating the average of each section:

This means that, if a score contains more than two sub-scores, the formula would make use of the sub-scores Numerators and Denominators like this:

This formula applies even if a sub-score contains more sub-scores, there are no limits for the amount of nested scores.

Go to the top

IMPORTANT: The Assessment Score (also referred to as Global Score) is determined by the score of the Critical Questions in the checklist. If a HNQIS 2.0 Checklist doesn't contain Critical Questions, the score will be determined by the Non-critical Questions.

After all the main scores are defined (Score 1, Score 2 and Score 3 for this example), now is time to define the Assessment Score Formula, which basically is calculated in the same way as a Score containing multiple sub-scores.

The only important consideration is that this formula only includes Critical Questions (while the other ones included both Critical and Non-critical questions). Remember that if a checklist contains only Non-critical Questions, the Assessment Score will be based on those questions instead of the Critical Questions.

The Numerators and Denominators for each score in the example are the following:

Now, using the formula defined in the previous section the Assessment Score of this example ends up being:

The formula for the Assessment Score in this example ended up including all the questions in the checklist due to the assumption made at the beginning of this section. Imagine for a moment that the only Critical Questions in the checklist were Q1, Q2, Q3, Q8 and Q9; in that case the Assessment Score formula would be the following:

The PCA will automatically manage all the Critical and Non-critical Questions, so you don't have to worry about dealing with those tedious calculations. This is how the last equation looks like for DHIS2:

((((#{_S1Q1}*2+#{_S1Q2}*2+#{_S1Q3}*2)+(#{_S3Q1}*2+#{_S3Q2}*2)))) / 
(((d2:countIfZeroPos('_S1Q1')*2+d2:countIfZeroPos('_S1Q2')*2+d2:countIfZeroPos('_S1Q3')*2)+(d2:countIfZeroPos('_S3Q1')*2+d2:countIfZeroPos('_S3Q2')*2)))

Go to the top

Previously, a special condition was presented to demonstrate the Assessment Score calculation. This condition was to assume that every question in the assessment was Critical, but in most cases, HNQIS Checklists contain a combination of Critical and Non-critical questions.

The Assessment Score will always be defined by the Critical Score, unless there are no Critical Questions in the Assessment. In the case that there are no Critical Questions, the Assesment Score will be defined by the Non-critical Score. Even if the Non-critical score is not always needed for the Assessment Score calculation, it's still used for the Competency Class Calculation.

Now, to define both formulas, the formula for Scores with multiple sub-scores is used as the base:

Then, taking into account that both the Numerator and Denominator can be split into Critical and Non-critical as briefly described previously, the Critical Score and Non-critical Score are defined as follows:

In the the Calculating the Assessment Score section, a new example was proposed were questions Q1, Q2, Q3, Q8 and Q9 were Critical and the others were Non-critical. This would result in the following Critical and Non-critical scores:

This surely is confusing, but don't worry, the PCA got you covered! Just keep in mind that all the other scores don't make a distinction between Critical and Non-critical questions, this is only used for the Assessment Score and the Competency Classification.

PRO TIP: The key to understand how these calculations work is to notice that all the formulas are basically the same. If a question is Critical, it'll be grouped with the Critical Numerators and Denominators, and if a question is Non-critical, it'll be grouped with the Non-critical Numerators and Denominators. Everything else is still the same.

Go to the top

As powerful as the scoring generation may seem, there are some important limitations to consider.

Scores and questions cannot be grouped together. This means that if a score contains a sub-score, it cannot contain questions like this:

A new score added that contains a sub-score and more questions.

This cannot be handled by the PCA as of v1.4.0, and will prevent the Set Up Program functionality from completing the process. To fix the issue in this example, questions Q15, Q16 and Q17 must be stored in another score like this:

Adding Score 4.2 to contain questions Q15, Q16 and Q17 would fix the issue.

Go to the top

Another important limitation is the consistency while using Feedback Orders. Feedback Order gaps are not allowed as those may present issues while using the Feedback Module in the Android App, so the PCA validates the Feedback Order of each question to ensure that those are continuous while also presenting recommended fixes.

NOTE: Remember that Feedback Order is the same as Compositive Indicator.

In the current example, defining the Score 6 would create a Feedback Order gap as all the scores would follow the sequence [ 1, 1.1, 1.2, 2, 2.1, 3, 4, 4.1, 4.2, 6 ], where the Score 5 is missing.

Many other scores can generate gaps, but you may be asking why isn't the jump from score 1.2 to 2 considered as a gap. Gaps at the end of a sub-sequence don't affect the Android App, but adding a score like 1.4 would generate a gap in the sub-sequence [ 1.1, 1.2, 1.4 ] as the Score 1.3 would be missing.

NOTE: Nested scores are considered sub-sequences, in this example the nested scores 1.1 and 1.2 are a sub-sequence of Score 1.

Below you'll find a table with many examples of correct and incorrect Feedback Order sequences, that may help clarify this concept.

Go to the top

Why as DEs with assign rule, instead of Prg Indicators

Scoring logic PR

WIP

Go to the top

Competency conditions Competency logic PR WIP

Go to the top

After a HNQIS 2.0 Program has been Validated and Saved, the Set Up Program button is enabled. This button creates all the necessary Program Rules for the Program to behave as an Assessment tool, this includes the Scores Calculations, Parent-Child Questions logic and more.

Message displayed after saving changes in a HNQIS 2.0 Program.

Set up Program button enabled.

Clicking this button starts the Metadata Building process that consists of five main steps:

1. Checking Scores
2. Reading assesment's questions
3. Building new metadata
4. Deleting old metadata
5. Importing new metadata

A window appears detailing the progress in the setup process in the form of a checklist of tasks.

Setup task progress checklist displayed in a pop-up window.

Each step will be detailed in the following sections.

WIP

Go to the top

WIP

Go to the top

WIP

Go to the top

WIP

Go to the top

WIP

Go to the top

WIP

Go to the top

WIP