Documentation and data model diagrams for categories

Resources - Ressources
1

I wonder how many users of DHIS2 find the terminology around categories, category options, category combinations, category option combinations, category option groups and category option group sets to be totally confusing. It does my head in any time I have to use them.

Earlier this year I started drawing an entity-relationship diagram to try to get my head around the concepts and to have an easy-to-understand reference. Of course life and work got in the way of me finishing this.

I have searched for anything in the DHIS2 documentation that could do the job (for example, something along the lines of the data model in the DHIS2 developer guide , but no joy yet. The closest thing I have found so far is this presentation by Jim Grace, which Jim pointed to from this discussion topic.

Searching this forum I have found quite a few discussions and questions on understanding and using disaggregations and attributes (two more examples here and here).

It is clear to me that there is a need for clarification and a good reference on this subject. I’m happy to work on this and share, but am wondering if someone has already done this and can share what they have done with the community. Obviously it would be great if such a reference found its way eventually into the DHIS2 documentation.

Cheers,

Hazim

4 Likes
2

Dear Hazim

Thanks for sharing and for the call for some user friendly explanation of this concept. We have also found it quite challenging and time consuming during the customisation academies, but it becomes easy with several examples especially for Categories, Category Options and category combinations…

The best approach has been first allowing participants create default data elements without category combination and look at it in data entry, then move on to category combination and provide quite a number of different data catgeoziation typical MoH aggregate reporting (by age, sex, location…)

You will see that default and categories are delivered as two separate sessions and given enough time.

The category - groups are better explained with analysis, so you need go to pivot tables to show how they work.

Read more here: Home - DHIS2 Documentation

Regards

2 Likes
3

I made a more recent version of the slides on category options, based on feedback from the slide deck mentioned by @Hazim_Timimi. I have also recorded a video presentation of the new slide deck at Attribute Option Combos etc - YouTube. Both the new and old slide decks include an overview of categories, options, combos and optionCombos, as used for disaggregations. They also go on to explain how these same objects can also be used as attribute option combos, such as for entering the same data for different accounts, projects, partners, etc.

The YouTube video description has a link to download the new slide deck as a PDF. The YouTube video is part of the DHIS2 YouTube channel at DHIS2 - YouTube.

@ben (Ben Guaraldi) is working on new content for the user manual to discuss how attribute categories (“AC”) work, and how they compare to disaggregation categories (“DC”). Hopefully that will be added to the documentation soon. But I’m not aware of other efforts to document the basics of how categories, options, combos and optionCombos relate to each other.

I think @prosper knows as well as anyone how to help users understand these concepts. I am someone who finds it useful to have diagrams and data models, though I expect that some others may learn it better in other ways. As I was learning the dhis2 schema, I created for myself the following partial data model that shows the table and column names that link to these objects. (It doesn’t show the links for sharing, but I think it shows everything else, or nearly so.) I found it handy in creating SQL queries because I could double click on the table or column name and copy-and-paste it into a query.

                                                       (disaggregation)  dataelement.categorycomboid
                                                            (attribute)  dataset.categorycomboid
                                                                                |
                                                                                |
dataelementcategory ---------- categorycombos_categories --------------- categorycombo
.categoryid                    .categoryid                               .categorycomboid
       |                       .categorycomboid                                 |
       |                                                                        |
categories_categoryoptions                                               categorycombos_optioncombos
.categoryid                                                              .categorycomboid
.categoryoptionid                                                        .categoryoptioncomboid
       |                                                                        |
       |                                                                        |
dataelementcategoryoption ---- categoryoptioncombos_categoryoptions ---- categoryoptioncombo
.categoryoptionid        \     .categoryoptionid                         .categoryoptioncomboid
       |                  \    .categoryoptioncomboid                   /       |
       |                   \                                           /        |
categoryoptiongroupmembers  \                  dataapproval           /  datavalue
.categoryoptionid            \                 .attributeoptioncomboid   .categoryoptioncomboid
.categoryoptiongroupid        \                                          .attributeoptioncomboid
       |                       \
       |                       categoryoption_organisationunits
categoryoptiongroup            .categoryoptionid    \
.categoryoptiongroupid         .organisationunitid   \
       |                                              \
       |                                               \
categoryoptiongroupsetmembers                  organisationunit
.categoryoptiongroupid                         .organisationunitid
.categoryoptiongroupsetid
       |
       |
categoryoptiongroupset ------- dataapprovallevel
.categoryoptiongroupsetid      .categoryoptiongroupsetid
5 Likes
4

Thank you very much @prosper and @Jim_Grace.

Prosper, your teaching method for explaining this is very nice – I may need to use it one day! I am aware of the documentation but was looking for something visual.

Jim, thanks for the new resources which I will check out. Thanks also for the data model. Like you, I find diagrams easier to understand than a whole bunch of text.

I just finished sketching out my own diagram using draw.io with Google Docs at DHIS2 categories - Google Drive

I wasn’t sure how to describe attributes, since my understanding from the documentation is that the DHIS2 model uses the same objects for both disaggregations (when applied to data elements) and attributes (when applied to data sets).

I think where things get a bit fuzzy in my head (and the documentation is not so clear) is how the various objects are used for disaggregation in pivot tables and data visualisations. I fudged this in my diagram with big arrows, but I am not sure I have got this right…

It would be great if @ben added diagrams to the new documentation!

2 Likes
5

Hazim, here’s how I would describe how analytics references these objects: When you add a category, there is a checkbox for “Data Dimension” that tells whether this category should be used as a dimension in analytics. If you check “Data Dimension”, then analytics displays a dimension whose values are the category options in this category. For each category, you also choose a “data dimension type” of “Disaggregation” or “Attribute”. If you have a “Disaggregation” category, then analytics can show data where the data value’s category option combo references a combination containing a selected category option. For example, if you check “Data Dimension” for a disaggregation category “Age”, then analytics will show an “Age” dimension with options such as “<15”, “15+”, or whatever category options are in the category “Age”. Then data is shown based on any category option combos that include the category options “<15” or “15+”. (The data could be disaggregated by a combination of a category “Age” and a category “Sex”, in which case choosing the dimension item “<15” will show data for the category option combinations “<15, Female” as well as “<15, Male”.)

If you have an “Attribute” category, then analytics can show data where the data value’s attribute option combination contains this category option. For example, if you check “Data Dimension” for an attribute category “Project”, then analytics will show a “Project” dimension with objects such as “Project 1234”, “Project 5678”, or whatever category options are in the category “Project”. Then data is shown based on any attribute option combos that include the category options “Project 1234” or “Project 5678”. (The attribute option combo could reference other attribute options, such as a combination of a category “Project” and a category “Open/Closed status”, in which case analytics would show data for the attribute option combinations “Project 1234, Open” as well as “Project 1234, Closed”.)

Likewise, When you add a Category Option Group Set (COGS), there is also a “Data Dimension” checkbox, and you also choose a data dimension type of “Disaggregation” or “Attribute”. If you check “Data Dimension”, then analytics will show this COGS as a dimension from which you can choose one or more Category Option Groups (COG’s) belonging to this group set. If you have a “Disaggregation” COGS, then data is shown based on any category option combos that include a category option belonging to a selected category option group. For example, you could create a disaggregation COGS “Child/Adult” with COG’s “Child” and “Adult”. The “Child” group could contain category options such as “0-2”, “3-5”, “6-14” as used in finer age disaggregations, and also the category option “<15”, as used in coarse age disaggregations. Then data is shown based on any of the category option combos (e.g. “3-5, Female”) containing a category option (e.g. “3-5”) belonging to a selected COG (e.g. “Child”.)

If you have an “Attribute” COGS with “Data Dimension” checked, then data is shown based on any attribute option combos that include a category option belonging to a selected category option group. For example, you could create an attribute COGS “Partner” with COG’s “Partner A” and “Partner B”. Partner A could be a group of category options “Project 1234” and “Project 5678”, and Partner B could be a group of category options “Project 2345” and “Project 6789”. Then data is shown based on any of the attribute option combos (e.g. “Project 1234, Open”) containing an attribute option (e.g. “Project 1234”) belonging to a selected COG (e.g., “Partner A”.)

How this all works in the database is that each analytics table contains a column for each data dimension (such as the disaggregation category “Age”, the attribute category “Project”, the disaggregation COGS “Child/Adult”, or the attribute COGS “Partner”.) Each row in the analytics table contains the UID (if any) for the item that may be selected in this dimension (such as the category option that may be selected for a category, or the COG that may be selected for a COGS.) So in your data model, you could show many-to-one relations from the analytics tables (of which there are several), to Category option, and to Category option group. These are not represented by foreign keys in the database, but are used by analytics to locate the dimension items selected.

I hope this helps!

3 Likes
6

Thanks very much for the detailed explanation, Jim.This is really useful.

I wonder now how best to translate the detail into one or two diagrams that people like me can use as a reference; a “cheat sheet” if you will. I have found these useful in other work.

I’ll keep plugging away at this!

Cheers,

Hazim

2 Likes
7

@Hazim_Timimi, by any chance have you managed to translate the details explained above into one or two diagrams? I am learning more about category combos in DHIS2 and the resources here have been very helpful.