Hierarchies

Hierarchies are important for explanatory variables. There are three types supported by PiArgus.

FlatHierarchy

The FlatHierarchy is used by default if no hierarchy is specified. All codes add up to a single total.

import piargus as pa

datacol = ["A", "B", "C", "B", "A"]
hierarchy = pa.FlatHierarchy(total_code="Total")

This creates a simple structure where all values are aggregated into one total.

        graph LR;
Total --> A;
Total --> B;
Total --> C;
    

LevelHierarchy

A LevelHierarchy is used when the hierarchical relationships are encoded directly within the data.

import piargus as pa

datacol = ["11123", "11234", "23456"]
hierarchy = pa.LevelHierarchy(levels=[2, 3], total_code="Total")

In this example, the first two digits represent a higher-level grouping, and the next 3 digits represent a more detailed level within that group.

        graph LR;
Total --> 11;
Total --> 23;
11 --> 123;
11 --> 234;
23 --> 456;
    

TreeHierarchy

A TreeHierarchy is used for complex hierarchies, typically stored in .hrc files.

import piargus as pa

datacol = ["PV20", "PV21", "PV22"]
hierarchy = pa.TreeHierarchy.from_hrc("provinces.hrc", total_code="NL01")

These hierarchies have a tree-like structure.

        graph LR;
NL01 --> LD01;
NL01 --> LD02;
LD01 --> PV20;
LD01 --> PV21;
LD02 --> PV22;
    

Creating a TreeHierarchy programmatically

You can also create a TreeHierarchy programmatically, without relying on an external .hrc file.

import piargus as pa

hierarchy = pa.TreeHierarchy(total_code="NL01")
hierarchy.create_node(["LD01", "PV20"])
hierarchy.create_node(["LD01", "PV21"])
hierarchy.create_node(["LD02", "PV22"])
hierarchy.to_hrc('provinces.hrc')

Attaching a hierarchy to inputdata

To apply a hierarchy to your data, simply pass the hierarchy as part of the MicroData or TableData constructor:

import piargus as pa

pa.MicroData(data_df, ...,
             hierarchies = {"region": region_hierarchy})

This will apply the specified region_hierarchy to the region column in your data.