dhis2-devs team mailing list archive

[noreply@xxxxxxxxxxxxx]

------------------------------------------------------------
revno: 841
committer: dhis2-c <dhis2@xxxxxxxxxxxxxx>
branch nick: dhis2-docbook-docs
timestamp: Thu 2013-10-17 00:14:17 -0400
message:
  Document new validation rule features in user manual quality chapter
modified:
  src/docbkx/en/dhis2_user_man_creating_data_quality.xml


--
lp:~dhis2-documenters/dhis2/dhis2-docbook-docs
https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs

Your team DHIS 2 developers is subscribed to branch lp:~dhis2-documenters/dhis2/dhis2-docbook-docs.
To unsubscribe from this branch go to https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs/+edit-subscription

=== modified file 'src/docbkx/en/dhis2_user_man_creating_data_quality.xml'
--- src/docbkx/en/dhis2_user_man_creating_data_quality.xml	2013-06-23 17:04:29 +0000
+++ src/docbkx/en/dhis2_user_man_creating_data_quality.xml	2013-10-17 04:14:17 +0000
@@ -1,4 +1,4 @@
-<?xml version='1.0' encoding='UTF-8'?>
+<?xml version='1.0' encoding='UTF-8'?>
 <!-- This document was created with Syntext Serna Free. --><!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "docbookV4.4/docbookx.dtd" []>
 <chapter>
   <title>Setting up Data Quality functionality</title>
@@ -55,15 +55,86 @@
   <section id="validationRule">
     <title>Validation Rule</title>
     <para>This module provides management of validation rules. A validation rule is based on an expression which defines a relationship between a number of data elements. The expression has a left side and a right side and an operator which defines whether the former must be less than, equal to or greater than the latter. The expression forms a condition which should assert that certain logical criteria are met. For instance, a validation rule could assert that the total number of vaccines given to infants is less than or equal to the total number of infants.</para>
-    <para>To add a validation rule, click the add new button. First, provide a descriptive <emphasis role="italic">name</emphasis> for the validation rule. The name must be unique among the validation rules. Second, provide a description for the validation rule. Third, select an operator. The operator options are <emphasis role="italic">equal</emphasis>, <emphasis role="italic">not equal</emphasis>, <emphasis role="italic">greater than</emphasis>, <emphasis role="italic">greater than or equal</emphasis>, <emphasis role="italic">less than</emphasis>, <emphasis role="italic">less than or equal to</emphasis> and <emphasis role="italic">compulsory pair</emphasis>. Then define the left side and right side of the validation rule expression. First, provide a description for the expression. Second, build the expression with the expression builder. The expression is mathematical and contain data elements as well as integers and mathematical operators. Data elements can be included by double-clicking one in the available data elements list to the right. Alternatively one can select a data element and click the insert button. Mathematical operators can be included by clicking the corresponding button under the expression builder area. Save the expression by clicking <emphasis role="italic">save</emphasis>, then save the validation rule by clicking <emphasis role="italic">save</emphasis>.</para>
-    <para>When defining the expression you can control whether the validation rule should be ignored or throw a violation when one or more data elements in the expression have no registered data values through the <emphasis role="italic">skip for missing values</emphasis> setting.</para>
-    <para>The compulsory pair operator allows you to require that data values must be entered for a form for all of the data elements in the expression, or none at all. In other words, you can require that if one field in a form is filled, then one or more other fields must also be filled.</para>
+    <para>To add a validation rule, just follow these steps:</para>
+    <itemizedlist>
+      <listitem>
+        <para>Click on the <emphasis role="italic">Add new</emphasis> button</para>
+      </listitem>
+      <listitem>
+        <para>Provide a descriptive <emphasis role="italic">Name</emphasis> for the validation rule. The name must be unique among the validation rules.</para>
+      </listitem>
+      <listitem>
+        <para>Provide a <emphasis role="italic">Description</emphasis> for the validation rule.</para>
+      </listitem>
+      <listitem>
+        <para>Select the <emphasis role="italic">Importance</emphasis> you wish to assign to the validation rule: <emphasis role="italic">high</emphasis>, <emphasis role="italic">medium</emphasis> or <emphasis role="italic">low</emphasis>.</para>
+      </listitem>
+      <listitem>
+        <para>Select the <emphasis role="italic">Rule type</emphasis>. For validating correct data, choose <emphasis role="italic">Validation</emphasis>. For monitoring  data according to a rule, choose <emphasis role="italic">Surveillance</emphasis> and follow the extra instructions below.</para>
+      </listitem>
+      <listitem>
+        <para>Select the <emphasis role="italic">Period type</emphasis> for the data being validated.</para>
+      </listitem>
+      <listitem>
+        <para>Select an <emphasis role="italic">Operator</emphasis>. The operator options are <emphasis role="italic">equal</emphasis>, <emphasis role="italic">not equal</emphasis>, <emphasis role="italic">greater than</emphasis>, <emphasis role="italic">greater than or equal</emphasis>, <emphasis role="italic">less than</emphasis>, <emphasis role="italic">less than or equal to</emphasis> and <emphasis role="italic">compulsory pair</emphasis>.</para>
+      </listitem>
+      <listitem>
+        <para>Define the <emphasis role="italic">left side</emphasis> and <emphasis role="italic">right side</emphasis> of the validation rule expression. First, provide a description for the expression. Second, build the expression with the expression builder. The expression is mathematical and contain data elements as well as integers and mathematical operators. Data elements can be included by double-clicking one in the available data elements list to the right. Alternatively one can select a data element and click the insert button. Mathematical operators can be included by clicking the corresponding button under the expression builder area.</para>
+      </listitem>
+      <listitem>
+        <para>Save each expression by clicking <emphasis role="italic">Save</emphasis>, then save the validation rule by clicking <emphasis role="italic">Save</emphasis>.</para>
+      </listitem>
+    </itemizedlist>
+    <para>When editing an expression, check the setting <emphasis role="italic">skip for missing values</emphasis> to require that all data element values in the expression must be present. If any values are missing, the validation rule will be skipped. If this setting is unchecked it means that the expression will be evaluated even if some of the values are missing.</para>
+    <para>The compulsory pair operator allows you to require that data values must be entered for a form for both left and right sides of the expression, or for neither side. In other words, you can require that if one field in a form is filled, then one or more other fields must also be filled.</para>
     <para>To edit a validation rule, click the <emphasis role="italic">edit</emphasis>icon next to the relevant validation rule in the list. Then follow the same procedures as above.</para>
-	<para>To delete a validation rule, click the <emphasis role="italic">delete</emphasis>icon next to the relevant validation rule in the list.</para>
+    <para>To delete a validation rule, click the <emphasis role="italic">delete</emphasis>icon next to the relevant validation rule in the list.</para>
     <para>To view validation rule details, click the <emphasis role="italic">view details</emphasis>icon next to the relevant validation rule in the list.</para>
   </section>
+  <section>
+    <title>Surveillance Rule</title>
+    <para>As well as checking for correct data, you can use a validation rules  to find unexpected data  values when compared with data from previous time periods. This kind of validation rules are called <emphasis role="italic">surveillance</emphasis> rules.</para>
+    <para>To add a surveillance rule, follow the steps above for validation rules, choosing a <emphasis role="italic">
+        <emphasis role="italic">rule type</emphasis>
+      </emphasis> of <emphasis role="italic">Surveillance</emphasis>. This adds the following validation rule options:</para>
+    <itemizedlist>
+      <listitem>
+        <para>Choose an <emphasis role="italic">Organisation unit level</emphasis> for this surveillance rule. If the data you wish to monitor is not entered at this level, it will be aggregated from lower level organisation units  in the organisation unit hierarchy.</para>
+      </listitem>
+      <listitem>
+        <para>Enter a <emphasis role="italic">Sequential sample count</emphasis>. This is the number of time periods immediately preceding against which you wish to compare the data. For example, if the  period type is <emphasis role="italic">Weekly</emphasis> and this count is 2, the current data will be compared with past  data averaged over each of the 2 previous weeks.</para>
+      </listitem>
+      <listitem>
+        <para>Enter an <emphasis role="italic">Annual sample count</emphasis>. This is the number of preceding years over which you will compare the data, from  periods at the same time of preceding years. For example if the period type is Weekly and the count is 3, data for a week starting on the first of September will be compared with data averaged over the week containing September 1 in each of the past 3 years.</para>
+        <para>The sequential sample count <emphasis role="italic">or</emphasis> annual sample count must be at least 1.</para>
+        <para>You may use the sequential and annual sample counts together. For example, say the period type is <emphasis role="italic">Weekly</emphasis>, the sequential count is 2, and the annual count is 3. The data will be compared with the average of the following time periods: the 2 weeks immediately preceding, and for each of the previous 3 years the data at the same time of year, plus the preceding 2 weeks, plus the following 2 weeks. This makes a total of  17 past periods: 2 immediate past periods plus 5 periods for each of the 3 preceding years. Be aware that when you have many past periods like this, evaluating the surveillance rule may take significant time and system resources.</para>
+      </listitem>
+      <listitem>
+        <para>Enter a number of <emphasis role="italic">High outliers</emphasis> of past data that you wish to exclude from comparison. This is useful if some past periods may have had unusually high data values, and you wish to compare against the average of all but the highest past period values. This gives the number of highest past period values to exclude before the past period values are averaged and compared with the current value.</para>
+      </listitem>
+      <listitem>
+        <para>Enter a number of <emphasis role="italic">Low outliers</emphasis> of past data that you wish to exclude from comparison. This is like High outliers except that it gives the number of lowest past period values to exclude before the past period values are averaged and compared with the current value.</para>
+        <para>You may use the high and low outliers in combination, but the sum of high outliers and low outliers must be less than the total number of past samples as determined by the sequential and annual sample counts. In the example above where there are 17 past periods, the sum of high and low outliers must be 16 or less.</para>
+        <para>If data is not found for all the desired past periods, the high and low outliers will be reduced in proportion to the number of periods for which data is found. For example, say we are looking for 17 past periods with high outliers set to 4 and low outliers set to 2. If data is found for only 9 of these past periods, only 2 high outliers will be discarded, and only 1 low outlier will be discarded.</para>
+      </listitem>
+    </itemizedlist>
+    <para>When a surveillance rule is evaluated, the <emphasis role="italic">left side</emphasis> of the equation is evaluated for the current period, and the <emphasis role="italic">right side</emphasis> is evaluated for each of the past periods. The right side  values for past periods are   averaged, and the average is  compared to the left side value according to the operator. Any high or low outliers are removed before the right-side average is taken.</para>
+    <para>A surveillance rule may contain data elements for periods that are longer than the period given for the rule. This is useful, for example, if you want to divide a data element value by the population count, and the population count is entered annually. The data for the longer period type (e.g. population count) must be entered for a period that overlaps with the start of the period being evaluated. For example, if the period being evaluated is the week starting January 6, 2014, the yearly population count must be entered for the year containing January 6 2014. If the data element is from a longer period type than the rule period type, it must have an aggregation operator of average, not sum. In other words, only data elements that don&apos;t sum through time (like population count) can be used from longer periods than the rule period.</para>
+    <para>For surveillance rules, the <emphasis role="italic">skip for missing</emphasis> option is given an additional meaning when data is being collected and aggregated from lower levels of the organisation unit hierarchy. When this option is selected and the data is present for some descendants at a lower level, but not all descendants at that level, the rule is skipped.</para>
+  </section>
   <section id="validationRuleGroup">
     <title>Validation Rule Group</title>
-    <para>A validation rule group provides a mechanism for classifying related data elements. Another advantage of using validation rule groups is that it can later be run separately, contrary to running all validation rules.</para>
+    <para>A validation rule group provides a mechanism for classifying related validation rules. Another advantage of using validation rule groups is that it can later be run separately, instead of running all validation rules.</para>
+    <para>You can also use a validation rule group to configure how users are notified of alerts from scheduled validation runs. To do this, you should identify a set of validation rules you want to evaluate regularly, and a set of users who should be notified of any exceptions to these rules. Then:</para>
+    <itemizedlist>
+      <listitem>
+        <para>Through User Management, make sure that a user role contains the users to be notified of theses results. This can be an existing role, or you may create a user role for this purpose.</para>
+      </listitem>
+      <listitem>
+        <para>Define a validation rule group for a set of validation rules. In the section User roles to alert, select one or more roles to which the users belong who should be notified.</para>
+      </listitem>
+    </itemizedlist>
+    <para>By repeating these two steps, you can build any set of relations between validation rules and users to fit your needs.</para>
+    <para>To enable routine scheduling of data validation runs, choose Data Administration from the Maintenance menu. Then click on Scheduling. If scheduling is active, click on the Stop button, then select the Data monitoring strategy of All daily. Finally enable scheduling by clicking on the Start button.</para>
   </section>
 </chapter>