Refactor create_hierarchy_dict function to improve readability and add documentation

isco.py

@@ -1,71 +1,42 @@
-# filename: isco.py
-from collections import defaultdict
+"""This module provides functionality for creating a hierarchy tree and a mapping from ISCO code to node name."""
+
 import csv
 
 
-def create_hierarchy_dict(filename):
+def create_hierarchy_dict(file: str) -> dict:
     """
-    Creates a dictionary where keys are nodes and values are sets of parent nodes representing the hierarchy of the ISCO-08 codes from the "unit" column of the isco_structure.csv file.
+    Creates a dictionary where keys are nodes and values are sets of parent nodes representing the group level hierarchy of the ISCO-08 structure.
+    The function assumes that the input CSV file has a column named 'unit' with the 4-digit ISCO-08 codes.
+    A csv file with the ISCO-08 structure can be downloaded from the International Labour Organization (ILO) at [https://www.ilo.org/ilostat-files/ISCO/newdocs-08-2021/ISCO-08/ISCO-08 EN.csv](https://www.ilo.org/ilostat-files/ISCO/newdocs-08-2021/ISCO-08/ISCO-08%20EN.csv)
 
     Args:
-    - filename: A string representing the path to the CSV file containing the ISCO-08 codes and their hierarchy.
+    - file: A string representing the path to the CSV file containing the 4-digit ISCO-08 codes.
 
     Returns:
     - A dictionary where keys are ISCO-08 unit codes and values are sets of their parent codes.
     """
     isco_hierarchy = {}
 
-    with open(filename, newline="") as csvfile:
+    with open(file, newline="") as csvfile:
         reader = csv.DictReader(csvfile)
         for row in reader:
             # Extract unit group level code (4 digits)
             unit_code = row["unit"].zfill(4)
+
             # Extract the parent code for the unit group level, which is the minor group level (3 digits)
-            parent_code = unit_code[:3]
+            minor_code = unit_code[0:3]
 
             # Add the unit code to the hierarchy with its parent code
-            isco_hierarchy[unit_code] = {parent_code}
+            isco_hierarchy[unit_code] = {minor_code}
 
-            # Additionally, we can add the parent's parent codes if needed
-            # For example, the major group level (1 digit) and sub-major group level (2 digits)
+            # Additionally, we can add the parent's parent codes at the sub-major group level (2 digits) and major group level (1 digit)
+            sub_major_code = unit_code[0:2]
             major_code = unit_code[0]
-            sub_major_code = unit_code[:2]
             isco_hierarchy[unit_code].update({major_code, sub_major_code})
 
     return isco_hierarchy
 
 
-def create_hierarchy_tree(hierarchy_dict: dict) -> tuple:
-    """
-    Builds the hierarchy tree and a mapping from name to ISCO code.
-
-    Args:
-    - hierarchy_dict: A dictionary representing the hierarchical structure.
-
-    Returns:
-    - tree: A dictionary representing the hierarchical structure.
-    - code_to_node: A dictionary mapping from ISCO code to node name.
-    """
-
-    tree = defaultdict(lambda: {"children": [], "parent": None})
-    code_to_node = {}
-
-    def add_node(parent_code, node):
-        code = node["name"].split("=")[0].strip()
-        code_to_node[code] = node["name"]
-        tree[code]["parent"] = parent_code
-        if parent_code:
-            tree[parent_code]["children"].append(code)
-        for child in node.get("children", []):
-            add_node(code, child)
-
-    add_node(None, hierarchy_dict)  # Root node has no parent
-    return tree, code_to_node
-
-
 # Example usage:
-# hierarchy_dict = create_hierarchy("ISCO_structure.csv")
-# tree, code_to_node = create_hierarchy_tree(hierarchy_dict)
+# hierarchy_dict = create_hierarchy_dict("ISCO_structure.csv")
 # print(hierarchy)
-# print(code_to_node)
-# print(tree)