dhis2-devs team mailing list archive
-
dhis2-devs team
-
Mailing list archive
-
Message #12715
[Branch ~dhis2-documenters/dhis2/dhis2-docbook-docs] Rev 360: More content in Mydatamart user manual
------------------------------------------------------------
revno: 360
committer: Bob Jolliffe bobjolliffe@xxxxxxxxx
branch nick: dhis2-docbook-docs
timestamp: Tue 2011-06-21 17:58:00 +0100
message:
More content in Mydatamart user manual
added:
src/docbkx/en/resources/images/mydatamart/configuration.png
src/docbkx/en/resources/images/mydatamart/data_mart_export.png
src/docbkx/en/resources/images/mydatamart/existing_connections.png
src/docbkx/en/resources/images/mydatamart/pivotwizard.png
src/docbkx/en/resources/images/mydatamart/views.png
modified:
src/docbkx/en/mydatamart_en.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/mydatamart_en.xml'
--- src/docbkx/en/mydatamart_en.xml 2011-06-20 23:22:00 +0000
+++ src/docbkx/en/mydatamart_en.xml 2011-06-21 16:58:00 +0000
@@ -97,7 +97,7 @@
shown in red in <xref linkend="dataflow_new"/>.</para>
<figure id="dataflow_new">
<title>Using a local datamart</title>
- <graphic align="center" width="4in"
+ <graphic align="center" width="5in"
fileref="resources/images/mydatamart/dataflow_new.png"/>
</figure>
<para>With the data available locally, pivot tables in the district office can now be
@@ -105,7 +105,7 @@
database server.</para>
</chapter>
-
+
<chapter>
<title>Installation</title>
<para>Installation of Mydatamart has been made as simple as possible. The application itself
@@ -194,114 +194,295 @@
image button bar immediately below the menu. If you hover your mouse slowly over these
buttons a tooltip window should show the functions of each.</para>
<section>
- <title>Creating a new datamart</title>
- <para>Now the main purpose of mydatamart is to manage your personal datamart files so
- the first thing you will need to do is to create a new datamart. You can create a
- new datamart either through the File->New menu option or by pressing the button with
- the blue cross. When you create this new datamart you will be prompted for a file
- name. The extension .dmart will be appended automatically to the name. Give some
- thought to how and where you are going to store this file as it will soon be full of
- valuable data so you really do need to look after it. You can create a backup at any
- time by simply making a copy of this file, eg. onto a USB memory stick.</para>
- <note>
- <para>The .dmart file is actually an sqlite3 database file which you can also open
- and view or edit with any sqlite3 capable tool, such as sqlitestudio.</para>
- </note>
- <para>When you create the new datamart, the application will present a dialog like <xref
- linkend="new"/>.</para>
- <figure id="new">
+ <title>Maintaining the local datamart</title>
+ <para/>
+ <section>
<title>Creating a new datamart</title>
- <graphic align="center" width="3in" fileref="resources/images/mydatamart/new.png"/>
- </figure>
- <para>The first thing you must do is to establish a connection with your dhis server. To
- do this enter the full url (including http://) of the dhis server into the box
- labelled <emphasis>URL</emphasis>. Then enter your online dhis user name and
- password. Your password will not be saved anywhere on your machine. To login press
- the button labelled <emphasis>Login</emphasis>. If the login was successful you will
- be rewarded with a green tick icon next to the login button.</para>
- <figure id="loggedin">
- <title>Logging in to dhis2 server</title>
- <graphic align="center" width="3in"
- fileref="resources/images/mydatamart/loggedin.png"/>
- </figure>
-
- </section>
- <section>
- <title>Populating the datamart with metadata</title>
- <para>The local datamart is designed to store aggregated data values from dataelements
- and indicators in the online DHIS2 application. But before you can do this, you must
- first populate the local datamart with <emphasis>metadata</emphasis> from the remote
- dhis2.</para>
- <para>Metadata refers to the parts of the database which give the data values meaning.
- This includes: <itemizedlist>
- <listitem>
- <para>Organisation units and hierarchy;</para>
- </listitem>
- <listitem>
- <para>Dataelement and Indicator names;</para>
- </listitem>
- <listitem>
- <para>Datavalue disaggregations (categories and categoryoptions);</para>
- </listitem>
- <listitem>
- <para>Various groups and groupsets.</para>
- </listitem>
- </itemizedlist> This information is required to work with pivot tables and to select
- important parameters relating to your organisation unit. </para>
- <para>Fortunately populating with metadata is a straightforward, if time consuming,
- operation. The easiest way to load metadata from DHIS2 is to press the toolbar
- button with the <inlinegraphic fileref="resources/images/mydatamart/hierarchy.png"/>
- image. It can also be done via the "Datamart->Load metadata from dhis" menu
- option.</para>
- <para>The Mydatamart application will then contact the remote DHIS2 server and download,
- transform and save the metadata into the local database.</para>
- <note>
- <para>Currently the transform part of the operation is quite slow. Expect it to take
- as long as ten minutes. During this time you cannot work with the application so
- you have to be patient. The reason for the long time is that it must process all
- of the orgunits in the dhis hierarchy, which for many countries can be quite
- large. In future editions of Mydatamart we will improve on this by cutting down
- the number of orgunits to be processed.</para>
- </note>
- <para>Once the metadata download is complete the user will be returned to the Settings
- interface where she can proceed to enter information about her organisation unit and
- the level of analysis to be used. This configuration is covered in the following
- section.</para>
- </section>
- <section>
- <title>Choosing Organisation unit and analysis level</title>
- <para/>
- <figure id="analysis_level">
- <title>Setting analysis parameters</title>
- <graphic align="center" width="3in"
- fileref="resources/images/mydatamart/analysis_level.png"/>
- </figure>
- </section>
- <section>
- <title>Downloading data</title>
- <para/>
- <figure id="download">
+ <para>Now the main purpose of mydatamart is to manage your personal datamart files
+ so the first thing you will need to do is to create a new datamart. You can
+ create a new datamart either through the File->New menu option or by pressing
+ the button with the blue cross. When you create this new datamart you will be
+ prompted for a file name. The extension .dmart will be appended automatically to
+ the name. Give some thought to how and where you are going to store this file as
+ it will soon be full of valuable data so you really do need to look after it.
+ You can create a backup at any time by simply making a copy of this file, eg.
+ onto a USB memory stick.</para>
+ <note>
+ <para>The .dmart file is actually an sqlite3 database file which you can also
+ open and view or edit with any sqlite3 capable tool, such as
+ sqlitestudio.</para>
+ </note>
+ <para>When you create the new datamart, the application will present a dialog like
+ <xref linkend="new"/>.</para>
+ <figure id="new">
+ <title>Creating a new datamart</title>
+ <graphic align="center" width="3in"
+ fileref="resources/images/mydatamart/new.png"/>
+ </figure>
+ <para>The first thing you must do is to establish a connection with your dhis
+ server. To do this enter the full url (including http://) of the dhis server
+ into the box labelled <emphasis>URL</emphasis>. Then enter your online dhis user
+ name and password. Your password will not be saved anywhere on your machine. To
+ login press the button labelled <emphasis>Login</emphasis>. If the login was
+ successful you will be rewarded with a green tick icon next to the login
+ button.</para>
+ <figure id="loggedin">
+ <title>Logging in to dhis2 server</title>
+ <graphic align="center" width="3in"
+ fileref="resources/images/mydatamart/loggedin.png"/>
+ </figure>
+ </section>
+ <section>
+ <title>Populating the datamart with metadata</title>
+ <para>The local datamart is designed to store aggregated data values from
+ dataelements and indicators in the online DHIS2 application. But before you can
+ do this, you must first populate the local datamart with
+ <emphasis>metadata</emphasis> from the remote dhis2.</para>
+ <para>Metadata refers to the parts of the database which give the data values
+ meaning. This includes: <itemizedlist>
+ <listitem>
+ <para>Organisation units and hierarchy;</para>
+ </listitem>
+ <listitem>
+ <para>Dataelement and Indicator names;</para>
+ </listitem>
+ <listitem>
+ <para>Datavalue disaggregations (categories and categoryoptions);</para>
+ </listitem>
+ <listitem>
+ <para>Various groups and groupsets.</para>
+ </listitem>
+ </itemizedlist> This information is required to work with pivot tables and to
+ select important parameters relating to your organisation unit. </para>
+ <para>Fortunately populating with metadata is a straightforward, if time consuming,
+ operation. The easiest way to load metadata from DHIS2 is to press the toolbar
+ button with the <inlinegraphic
+ fileref="resources/images/mydatamart/hierarchy.png" width="0.5cm"/> image.
+ It can also be done via the "Datamart->Load metadata from dhis" menu
+ option.</para>
+ <para>The Mydatamart application will then contact the remote DHIS2 server and
+ download, transform and save the metadata into the local database.</para>
+ <note>
+ <para>Currently the transform part of the operation is quite slow. Expect it to
+ take as long as ten minutes. During this time you cannot work with the
+ application so you have to be patient. The reason for the long time is that
+ it must process all of the orgunits in the dhis hierarchy, which for many
+ countries can be quite large. In future editions of Mydatamart we will
+ improve on this by cutting down the number of orgunits to be
+ processed.</para>
+ </note>
+ <para>Once the metadata download is complete the user will be returned to the
+ Settings interface where she can proceed to enter information about her
+ organisation unit and the level of analysis to be used. This configuration is
+ covered in the following section.</para>
+ </section>
+ <section>
+ <title>Choosing Organisation unit and analysis level</title>
+ <para>The benefit of using mydatamart is that you only need to download the data
+ from the dhis2 server which you need in your routine analysis. By selecting the
+ appropriate orgunit and level of analysis you ensure that your regular data
+ updates will be small and manageable even when bandwidth is limited.</para>
+ <para>The two concepts to be aware of are your <emphasis>root orgunit</emphasis> and
+ your <emphasis>analysis level</emphasis>. To illustrate this using an example
+ from Kenya, let us assume you are based in the district office of Nyeri North in
+ Nyeri County. You have either been given pivot tables or you will make them to
+ analyze your data down to facility level. So you require data for all the
+ facilities within Nyeri North and you also require to see data for your peers
+ ie. the other districts within Nyeri County.</para>
+ <para>Once you have created a new datamart and have downloaded metadata as described
+ in the previous section, you should be able to set these two parameters in the
+ settings dialog as illustrated below. If the dialog is not visible you can
+ access it by pressing the <inlinegraphic
+ fileref="resources/images/mydatamart/configuration.png" width="0.5cm"/>
+ button.</para>
+ <figure id="analysis_level">
+ <title>Setting analysis parameters</title>
+ <graphic align="center" width="3in"
+ fileref="resources/images/mydatamart/analysis_level.png"/>
+ </figure>
+ <para>Once you have set these once they will be saved with your datamart file.
+ Though they can be changed at any time or you might have different datamart
+ files with different settings. In most cases you will likely be maintaining a
+ single datamart file which you will have set up like the case of Nyeri North
+ above.</para>
+ <note>
+ <para>You will have noticed from <xref linkend="analysis_level"/> that the
+ analysis level is converted to a number. So for example, in Kenya, the
+ facility is at level 5, the district is level 4 etc. These correspond to
+ orgunit hierarchy levels within dhis2. These numbers will vary from one
+ country implementation to another. For the most part you do not need to be
+ concerned with the number of the level, except when you come to selecting
+ views for analysis. Here you will see that the level number is used as part
+ of the naming convention for views.</para>
+ </note>
+ </section>
+ <section>
<title>Downloading data</title>
- <graphic align="center" width="3in"
- fileref="resources/images/mydatamart/download.png"/>
- </figure>
- </section>
- <section>
- <title>Creating new pivot tables</title>
- <para/>
- </section>
- <section>
- <title>Linking to shared pivot tables</title>
- <para/>
- </section>
+ <para>Now that you have your local datamart set up you are ready to start populating
+ it with data from your online dhis2 server. Whereas you will probably only
+ adjust the settings when creating a new datamart, you will be doing regular
+ synching of your local datamart with the online server. If data is being
+ downloaded once a month, then the incremental size of each download will be
+ small. You can get to the data download screen either by pressing the
+ <inlinegraphic fileref="resources/images/mydatamart/data_mart_export.png"
+ width="0.5cm"/> button or by navigating to the "Datamart->Update Aggregate
+ Data" menu item.</para>
+ <para><xref linkend="download"/>, shows the datamart update screen. You can set the
+ detailed options for your download here. There is not much to be done as the
+ defaults should match your typical operations.</para>
+ <figure id="download">
+ <title>Downloading data</title>
+ <graphic align="center" width="3in"
+ fileref="resources/images/mydatamart/download.png"/>
+ </figure>
+ <para>On the left hand side there are check boxes which you should set to indicate
+ whether you need data weekly, monthly, quarterly or yearly (you can select more
+ than one). These are independently set for aggregated datavaues as well as
+ aggregated indicator values, though in most cases you will require the same
+ periodicity of databvalue and indicator value.</para>
+ <para>On the right hand side you have the option to set the time period you are
+ downloading. The application will attempt to select a reasonable period for you.
+ Other than the very first time you download data, the default should be to
+ download the previous month's data.</para>
+ <para>Below the period selection section are the two buttons which actually initiate
+ the download. The first button is used to download data for orgunits below the
+ root orgunit at the level which was specified previously. So in the example, it
+ will download aggregated data at the facility level (level 5) for facilities in
+ Nyere North.</para>
+ <para>The second button is used to download aggregate data of our peers. In this
+ case it would ensure that we had data for all the districts in Nyere County.
+ This will allow the Nyere North user to analyze the data for all facilities in
+ Nyere North as well as to compare the performance of Nyere North district with
+ Nyere South district.</para>
+ </section>
+ </section>
+ <section>
+ <title>Working with Excel</title>
+ <section>
+ <title>Creating a new Excel workbook for analysis</title>
+ <para>Pivot tables in Microsoft Excel are commonly used to analyze data in dhis2.
+ The mydatamart tool does not create pivot tables for you, but it does provide a
+ simple interface to get you started with an Excel workbook which is already
+ linked to views in your local datamart. This means that users do not need to
+ concern themselves with the technical detail of ODBC connection strings, DSNs or
+ what have you. This section describes how you get started with that. It does not
+ go into the detail of actually designing the pivot tables as this is described
+ elsewhere in the dhis2 user manual.</para>
+ <para>The most important thing to have prepared when designing a pivot table are the
+ database views you will use. Mydatamart automatically creates some "standard"
+ views for dataelement values and indicator values for different periodicities -
+ weekly, monthly, quarterly, semesterly (every 6 months), yearly etc. Expert
+ users might also want to design additional custom views. Using a 3rd party tool
+ such as sqlstudio is useful for this. There is also an option to import an
+ arbitrary sql file into the database which can be used to share custom
+ views.</para>
+ <para>To start the process of creating an Excel pivot table workbook, the user
+ should select "Reports->New Excel file" from the menu bar. She will immediately
+ be greeted with a dialog for selecting views such as illustrated in <xref
+ linkend="views"/> below.</para>
+ <figure id="views">
+ <title>Selecting views</title>
+ <graphic align="center" width="3in"
+ fileref="resources/images/mydatamart/views.png"/>
+ </figure>
+ <para>Mydatamart will present a list of all defined views in the listbox on the
+ left. These include the automatically generated ones as well as any custom views
+ which may have been created outside of the tool. The names of the views give
+ some indication of their content. The auto generated views are named as
+ follows:</para>
+ <para><code>pivotsource_<datatype>_ou_<level>_<periodicity></code></para>
+ <para>In <xref linkend="views"/> we can see that monthly and quarterly views for
+ indicators at level 4 (district) and 5 (facility) have been selected.
+ Double-clicking on a view in the left listbox causes the view to be selected for
+ inclusion. Similarly, double-clicking on a view in the right listbox causes the
+ view to be removed from the selection.</para>
+ <note>
+ <para>A warning to power users creating custom views. You can name these views
+ whatever you like, but be sure not to use the name of one of the built in
+ views. If you do that your custom view will get overwritten when the
+ metadata is updated.</para>
+ </note>
+ <para>Once you have selected the required views you can click on "Create Excel
+ workbook". This will prompt you for a name and location for your new Excel
+ file.</para>
+ </section>
+ <section>
+ <title>Working with your new Excel file</title>
+ <para>When you create a new Excel file as described in the section above, Excel
+ should automatically open the new file. This file will have the database
+ connections to your selected views already populated. To see these connections
+ (on Excel 2007) first click on the "Data" menu, then select "Existing
+ Connections" from the toolbar. You should see something like <xref
+ linkend="existing_connections"/> below, showing the views that you selected
+ in the previous step.</para>
+ <figure id="existing_connections">
+ <title>Datamart connections</title>
+ <graphic align="center" width="4in"
+ fileref="resources/images/mydatamart/existing_connections.png"/>
+ </figure>
+ <para>You can use these views to create pivot tables or simply to view the data
+ within a worksheet. To make use of a view simply double click on it. You will be
+ presented with a dialog similar to <xref linkend="pivotwizard"/>.</para>
+ <figure id="pivotwizard">
+ <title>Pivot report wizard</title>
+ <graphic align="center" width="3in"
+ fileref="resources/images/mydatamart/pivotwizard.png"/>
+ </figure>
+ <para>From this point, creating pivot tables is the same as is described in the
+ DHIS2 User Manual.</para>
+ <note>
+ <para>Remember to define the Indicator value calculation when using indicator
+ views. This process is as described in the DHIS2 User Manual.</para>
+ </note>
+ <para>On completion of your pivot table design you can save it and/or copy it to a
+ new location. Whenever you have new data in your datamart you can refresh the
+ pivot tables. Refresh times should be reasonably fast as the data is coming from
+ your local datamart file.</para>
+ <para>You can also share your pivot design with other mydatamart users, particularly
+ those at the same administrative level as yourself, as they will likely be
+ interested in the same views and analysis. To do this you should first ensure
+ that the Excel pivot cache is empty so that you are not trying to send enormous
+ files around by email (<emphasis>Instructions required on doing this -
+ Ed.</emphasis>).</para>
+ <para>Remember that the database links in the Excel file are pointing at your
+ datamart file (the file with a .dmart extension which you create when starting a
+ new datamart). If you move that datamart file your connections will no longer
+ work. Similarly if you send the file to someone else, they will need to connect
+ the Excel file to their own datamart. This process is straightforward and is
+ described in the next section.</para>
+ </section>
+ <section>
+ <title>Linking an existing Excel file to a datamart</title>
+ <para>If you have been sent a pivot table report from another mydatamart user, or you have moved the location of your .dmart file
+ you will need to recreate the link between your datamart and the Excel file. This is accomplished simply:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Open your datamart file using the mydatamart tool;</para>
+ </listitem>
+ <listitem>
+ <para>Select "Reports->Connect to existing excel file" or use the
+ <inlinegraphic fileref="resources/images/mydatamart/excel.png"/>
+ shortcut</para>
+ </listitem>
+ <listitem><para>Select the excel file you wish to connect to in the ensuing dialog.</para></listitem>
+ </itemizedlist>
+ <para>The excel file will automatically have its database links <emphasis>repaired</emphasis> to point to your current datamart.</para>
+ </section>
+ </section>
+
<section>
<title>Troubleshooting</title>
- <para/>
+ <para>In the event of things not behaving as expected, or if you wish to report buggy or surprizing behaviour, it can be
+ useful (particularly for the developer) to have more detailed information than that which is normally displayed to the user.</para>
+ <para>The mydatamart application creates an internal log with lots of low level information about what the program is doing at any
+ point in time. To view this internal log you need to display the program console. You can either do this through the "Help" menu
+ option or by simply pressing the "F2" shortcut key.</para>
+ <para>It is a good idea to capture the content of this console log when reporting problems to the developers.</para>
</section>
</chapter>
<chapter>
<title>Summmary notes</title>
- <para/>
+ <para><emphasis>Put some short quick reference notes for common tasks here - Ed.</emphasis></para>
</chapter>
</book>
=== added file 'src/docbkx/en/resources/images/mydatamart/configuration.png'
Binary files src/docbkx/en/resources/images/mydatamart/configuration.png 1970-01-01 00:00:00 +0000 and src/docbkx/en/resources/images/mydatamart/configuration.png 2011-06-21 16:58:00 +0000 differ
=== added file 'src/docbkx/en/resources/images/mydatamart/data_mart_export.png'
Binary files src/docbkx/en/resources/images/mydatamart/data_mart_export.png 1970-01-01 00:00:00 +0000 and src/docbkx/en/resources/images/mydatamart/data_mart_export.png 2011-06-21 16:58:00 +0000 differ
=== added file 'src/docbkx/en/resources/images/mydatamart/existing_connections.png'
Binary files src/docbkx/en/resources/images/mydatamart/existing_connections.png 1970-01-01 00:00:00 +0000 and src/docbkx/en/resources/images/mydatamart/existing_connections.png 2011-06-21 16:58:00 +0000 differ
=== added file 'src/docbkx/en/resources/images/mydatamart/pivotwizard.png'
Binary files src/docbkx/en/resources/images/mydatamart/pivotwizard.png 1970-01-01 00:00:00 +0000 and src/docbkx/en/resources/images/mydatamart/pivotwizard.png 2011-06-21 16:58:00 +0000 differ
=== added file 'src/docbkx/en/resources/images/mydatamart/views.png'
Binary files src/docbkx/en/resources/images/mydatamart/views.png 1970-01-01 00:00:00 +0000 and src/docbkx/en/resources/images/mydatamart/views.png 2011-06-21 16:58:00 +0000 differ
