How Do Tag Hierarchies Work? – Learnosity Author Guide

Tag hierarchies are a way of grouping related Tag types together. The main use of Tag hierarchies is to configure the drill-down behaviour for Tag based reports. The following sections describe how to design, create and use your Tag hierarchies.

Drill down reporting

A common use case in reporting is to provide a summarised view of data with the ability to drill down into specific areas of interest. In learning and assessment, it can be useful to see a summary of a student’s performance across broad subject areas, with the option of drilling into a specific study unit to identify gaps in the student’s knowledge.

This kind of analytical reporting can be achieved easily with Reports API and Tag hierarchies. A Tag hierarchy defines how Reports API will summarise and group the assessment results in a drill-down report.

Designing Tag hierarchies

Tag hierarchies group two or more Tag types into a hierarchical structure. The hierarchy defines the order of the Tag types, from the broad summary level to the detailed granular level. For Items to be detected and reported as part of a Tag hierarchy, the Item needs to be tagged with a value for each Tag type in the hierarchy.

Here are two examples showing different Tag hierarchies and how they might be used.

Subject-topic example

A set of school subjects can each be divided into a granular set of topic areas. This Tag hierarchy would be defined as:

Level 1: Subject
Level 2: Topic

Figure 1: Subject-topic Tag hierarchy example.

For this Tag hierarchy, items would need to be tagged with the Subject and the Topic they relate to:

An Item about the properties of right-angled triangles could be tagged Subject:Math, Topic:Geometry.
An Item about the probability of dice rolls could be tagged Subject:Math, Topic:Statistics.
An Item about single-celled organisms could be tagged Subject:Science, Topic:Biology.

Unit-chapter-exercise-difficulty example

An online course is divided into units and chapters. Each chapter has some test exercises. Each exercise Question has a difficulty rating of basic, intermediate or advanced. This Tag hierarchy could be defined as:

Level 1: Unit
Level 2: Chapter
Level 3: Exercise
Level 4: Difficulty

Figure 2: Unit-chapter-exercise-difficulty, a larger Tag hierarchy example.

For this Tag hierarchy, Items would need to be tagged with the Unit, Chapter, Exercise and Difficulty rating:

An introductory Item about the Amazon rainforest could be tagged Unit:1-ecosystems, Chapter:1.1-biomes, Exercise:1.1a, Difficulty:Basic.
A chapter-review Item about greenhouse gases could be tagged Unit:1-ecosystems, Chapter:1.2-climate-science, Exercise:1.2d, Difficulty:Intermediate.
A complex word problem involving mass and acceleration could be tagged Unit:2-physics, Chapter:2.2-motion, Exercise:2.2b, Difficulty:Advanced.

Using Tag hierarchies

Reports API uses Tag hierarchies to summarise and display assessment results in drill-down reports. The relevant report types accept a Tag hierarchy reference. Those reports will aggregate assessment scores according to the Tags applied to each Item.

Taking the subject-topic hierarchy as an example:

The Sessions Summary by Tag report will display a percentage score for English, which is the percentage score achieved across all items in the assessment tagged Subject:English. If the assessment also contains items tagged Subject:Math, the report will show a separate percentage for Math.
The report also provides drill down functionality, which provides a breakdown of percentage scores for each Tag from the second level of the hierarchy - in this case, the Topic areas. If each English Item is also tagged with Topic:Comprehension, Topic:Writing or Topic:Grammar, the English score will be broken down by those Topics. The score for each Topic is calculated as the percentage score for the set of Items associated with that Topic tag. Similarly, the score for Math Items will be reported by Algebra, Geometry and Statistics scores.

This example demonstrates the interplay between Tag hierarchies and the Tag values applied to an Item. The Tag hierarchy dictates which Tag type to use for the high level summary, and which to use for lower level breakdown. The actual category names that appear in the report are taken from the Tag values applied to the Items in an assessment.

Reporting with large Tag hierarchies

For Tag hierarchies that have many levels, it may be desirable to view the score breakdown for a specific branch of the hierarchy. Some reports can accept a Tag hierarchy path parameter, which is used to render the report starting from that point in the hierarchy.

Taking the unit-chapter-exercise-difficulty hierarchy as an example, we might want to see the score for exercise 2.2a, broken down by Question difficulty. We could use the Progress by Tag by User report as follows:

{
   "id": "report-1",
   "type": "progress-by-tag-by-user",
   "users": [
      {
         "id": "12345678",
         "name": "Walter White"
      }
   ],
   "hierarchy_reference": "unit-chapter-exercise-difficulty",
   "tag_hierarchy_path": [
      {
         "type": "unit",
         "name": "2-physics"
      },
      {
         "type": "chapter",
         "name": "2.2-motion"
      },
      {
         "type": "exercise",
         "name": "2.2a"
      }
   ]
}

Creating Tag Hierarchies

See our article about creating Tag hierarchies here.