MetaCode and MetaCodeList classes with allowed_values attribute

nomenclature/code.py

@@ -209,3 +209,16 @@ class RegionCode(Code):
     """
 
     hierarchy: str = None
+
+
+class MetaCode(Code):
+    """A subclass of Code
+
+    Attributes
+    ----------
+    allowed_values : Optional(list[any])
+        An optional list of allowed values
+
+    """
+
+    allowed_values: Optional[List[Any]]

nomenclature/codelist.py

@@ -9,7 +9,7 @@
 from pyam.utils import write_sheet
 from pydantic import BaseModel, validator
 
-from nomenclature.code import Code, VariableCode, RegionCode
+from nomenclature.code import Code, VariableCode, RegionCode, MetaCode
 from nomenclature.error.codelist import DuplicateCodeError
 from nomenclature.error.variable import (
     MissingWeightError,
@@ -624,3 +624,62 @@ def filter(self, hierarchy: str) -> "RegionCodeList":
                 "Use `RegionCodeList.hierarchy` method for available items."
             )
             raise ValueError(msg)
+
+
+class MetaCodeList(CodeList):
+    """A subclass of CodeList specified for MetaCodes
+
+    Attributes
+    ----------
+    name : str
+        Name of the MetaCodeList
+    mapping : dict
+        Dictionary of `MetaCode` objects
+
+    """
+
+    # class variable
+    code_basis: ClassVar = MetaCode
+    validation_schema: ClassVar[str] = "meta indicators"
+
+    @classmethod
+    def from_yaml_files(cls, name: str, path: Path, file_glob_pattern: str = "**/*"):
+        """Initialize a MetaCodeList from file(s) with MetaCodes
+
+        Parameters
+        ----------
+        name : str
+            Name of the MetaCodeList
+        path : :class:`pathlib.Path` or path-like
+            Directory with the codelist files
+        file_glob_pattern : str, optional
+            Pattern to downselect codelist files by name, default: "**/*" (i.e. all
+            files in all sub-folders)
+
+        Returns
+        -------
+        MetaCodeList
+
+        """
+        mapping: Dict[str, MetaCode] = {}
+        code_list: List[MetaCode] = []
+
+        for yaml_file in (
+            f for f in path.glob(file_glob_pattern) if f.suffix in {".yaml", ".yml"}
+        ):
+            with open(yaml_file, "r", encoding="utf-8") as stream:
+                _code_list = yaml.safe_load(stream)
+
+            for top_level_cat in _code_list:
+                code = MetaCode(
+                    name=list(top_level_cat.keys())[0],
+                    mapping=top_level_cat,
+                )
+                code.file = yaml_file.relative_to(path.parent).as_posix()
+                code.allowed_values = list(top_level_cat.values())[1]
+                code_list.append(code)
+
+        for code in code_list:
+            mapping[code.name] = code
+
+        return cls(name=name, mapping=mapping)

nomenclature/definition.py

@@ -1,139 +1,143 @@
-import logging
-from pathlib import Path
-
-import pandas as pd
-from pyam import IamDataFrame
-from pyam.index import replace_index_labels
-from pyam.logging import adjust_log_level
-
-from nomenclature.codelist import CodeList, RegionCodeList, VariableCodeList
-from nomenclature.validation import validate
-
-logger = logging.getLogger(__name__)
-SPECIAL_CODELIST = {"variable": VariableCodeList, "region": RegionCodeList}
-
-
-class DataStructureDefinition:
-    """Definition of datastructure codelists for dimensions used in the IAMC format"""
-
-    def __init__(self, path, dimensions=["region", "variable"]):
-        """
-
-        Parameters
-        ----------
-        path : str or path-like
-            The folder with the project definitions.
-        dimensions : list of str, optional
-            List of :meth:`CodeList` names. Each CodeList is initialized
-            from a sub-folder of `path` of that name.
-        """
-        if not isinstance(path, Path):
-            path = Path(path)
-
-        if not path.is_dir():
-            raise NotADirectoryError(f"Definitions directory not found: {path}")
-
-        self.dimensions = dimensions
-        for dim in self.dimensions:
-            self.__setattr__(
-                dim, SPECIAL_CODELIST.get(dim, CodeList).from_directory(dim, path / dim)
-            )
-
-        empty = [d for d in self.dimensions if not self.__getattribute__(d)]
-        if empty:
-            raise ValueError(f"Empty codelist: {', '.join(empty)}")
-
-    def validate(self, df: IamDataFrame, dimensions: list = None) -> None:
-        """Validate that the coordinates of `df` are defined in the codelists
-
-        Parameters
-        ----------
-        df : :class:`pyam.IamDataFrame`
-            Scenario data to be validated against the codelists of this instance.
-        dimensions : list of str, optional
-            Dimensions to perform validation (defaults to all dimensions of self)
-
-        Returns
-        -------
-        None
-
-        Raises
-        ------
-        ValueError
-            If `df` fails validation against any codelist.
-        """
-        validate(self, df, dimensions=dimensions or self.dimensions)
-
-    def check_aggregate(self, df: IamDataFrame, **kwargs) -> None:
-        """Check for consistency of scenario data along the variable hierarchy
-
-        Parameters
-        ----------
-        df : :class:`pyam.IamDataFrame`
-            Scenario data to be checked for consistency along the variable hierarchy.
-        kwargs : Tolerance arguments for comparison of values
-            Passed to :any:`numpy.isclose` via :any:`pyam.IamDataFrame.check_aggregate`.
-
-        Returns
-        -------
-        :class:`pandas.DataFrame` or None
-            Data where a variable and its computed aggregate does not match.
-
-        Raises
-        ------
-        ValueError
-            If the :any:`DataStructureDefinition` does not have a *variable* dimension.
-        """
-        if "variable" not in self.dimensions:
-            raise ValueError("Aggregation check requires 'variable' dimension.")
-
-        lst = []
-
-        with adjust_log_level(level="WARNING"):
-            for code in df.variable:
-                attr = self.variable.mapping[code]
-                if attr.check_aggregate:
-                    components = attr.components
-
-                    # check if multiple lists of components are given for a code
-                    if isinstance(components, dict):
-                        for name, _components in components.items():
-                            error = df.check_aggregate(code, _components, **kwargs)
-                            if error is not None:
-                                error.dropna(inplace=True)
-                                # append components-name to variable column
-                                error.index = replace_index_labels(
-                                    error.index, "variable", [f"{code} [{name}]"]
-                                )
-                                lst.append(error)
-
-                    # else use components provided as single list or pyam-default (None)
-                    else:
-                        error = df.check_aggregate(code, components, **kwargs)
-                        if error is not None:
-                            lst.append(error.dropna())
-
-        if lst:
-            # there may be empty dataframes due to `dropna()` above
-            error = pd.concat(lst)
-            return error if not error.empty else None
-
-    def to_excel(
-        self, excel_writer, sheet_name=None, sort_by_code: bool = False, **kwargs
-    ):
-        """Write the *variable* codelist to an Excel sheet
-
-        Parameters
-        ----------
-        excel_writer : path-like, file-like, or ExcelWriter object
-            File path as string or :class:`pathlib.Path`,
-            or existing :class:`pandas.ExcelWriter`.
-        sheet_name : str, optional
-            Name of sheet that will have the codelist. If *None*, use the codelist name.
-        sort_by_code : bool, optional
-            Sort the codelist before exporting to file.
-        **kwargs
-            Passed to :class:`pandas.ExcelWriter` (if *excel_writer* is path-like).
-        """
-        # TODO write all dimensions to the file
-        self.variable.to_excel(excel_writer, sheet_name, sort_by_code, **kwargs)
+import logging
+from pathlib import Path
+
+import pandas as pd
+from pyam import IamDataFrame
+from pyam.index import replace_index_labels
+from pyam.logging import adjust_log_level
+
+from nomenclature.codelist import (
+    CodeList,
+    RegionCodeList,
+    VariableCodeList,
+)
+from nomenclature.validation import validate
+
+logger = logging.getLogger(__name__)
+SPECIAL_CODELIST = {"variable": VariableCodeList, "region": RegionCodeList}
+
+
+class DataStructureDefinition:
+    """Definition of datastructure codelists for dimensions used in the IAMC format"""
+
+    def __init__(self, path, dimensions=["region", "variable"]):
+        """
+
+        Parameters
+        ----------
+        path : str or path-like
+            The folder with the project definitions.
+        dimensions : list of str, optional
+            List of :meth:`CodeList` names. Each CodeList is initialized
+            from a sub-folder of `path` of that name.
+        """
+        if not isinstance(path, Path):
+            path = Path(path)
+
+        if not path.is_dir():
+            raise NotADirectoryError(f"Definitions directory not found: {path}")
+
+        self.dimensions = dimensions
+        for dim in self.dimensions:
+            self.__setattr__(
+                dim, SPECIAL_CODELIST.get(dim, CodeList).from_directory(dim, path / dim)
+            )
+
+        empty = [d for d in self.dimensions if not self.__getattribute__(d)]
+        if empty:
+            raise ValueError(f"Empty codelist: {', '.join(empty)}")
+
+    def validate(self, df: IamDataFrame, dimensions: list = None) -> None:
+        """Validate that the coordinates of `df` are defined in the codelists
+
+        Parameters
+        ----------
+        df : :class:`pyam.IamDataFrame`
+            Scenario data to be validated against the codelists of this instance.
+        dimensions : list of str, optional
+            Dimensions to perform validation (defaults to all dimensions of self)
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        ValueError
+            If `df` fails validation against any codelist.
+        """
+        validate(self, df, dimensions=dimensions or self.dimensions)
+
+    def check_aggregate(self, df: IamDataFrame, **kwargs) -> None:
+        """Check for consistency of scenario data along the variable hierarchy
+
+        Parameters
+        ----------
+        df : :class:`pyam.IamDataFrame`
+            Scenario data to be checked for consistency along the variable hierarchy.
+        kwargs : Tolerance arguments for comparison of values
+            Passed to :any:`numpy.isclose` via :any:`pyam.IamDataFrame.check_aggregate`.
+
+        Returns
+        -------
+        :class:`pandas.DataFrame` or None
+            Data where a variable and its computed aggregate does not match.
+
+        Raises
+        ------
+        ValueError
+            If the :any:`DataStructureDefinition` does not have a *variable* dimension.
+        """
+        if "variable" not in self.dimensions:
+            raise ValueError("Aggregation check requires 'variable' dimension.")
+
+        lst = []
+
+        with adjust_log_level(level="WARNING"):
+            for code in df.variable:
+                attr = self.variable.mapping[code]
+                if attr.check_aggregate:
+                    components = attr.components
+
+                    # check if multiple lists of components are given for a code
+                    if isinstance(components, dict):
+                        for name, _components in components.items():
+                            error = df.check_aggregate(code, _components, **kwargs)
+                            if error is not None:
+                                error.dropna(inplace=True)
+                                # append components-name to variable column
+                                error.index = replace_index_labels(
+                                    error.index, "variable", [f"{code} [{name}]"]
+                                )
+                                lst.append(error)
+
+                    # else use components provided as single list or pyam-default (None)
+                    else:
+                        error = df.check_aggregate(code, components, **kwargs)
+                        if error is not None:
+                            lst.append(error.dropna())
+
+        if lst:
+            # there may be empty dataframes due to `dropna()` above
+            error = pd.concat(lst)
+            return error if not error.empty else None
+
+    def to_excel(
+        self, excel_writer, sheet_name=None, sort_by_code: bool = False, **kwargs
+    ):
+        """Write the *variable* codelist to an Excel sheet
+
+        Parameters
+        ----------
+        excel_writer : path-like, file-like, or ExcelWriter object
+            File path as string or :class:`pathlib.Path`,
+            or existing :class:`pandas.ExcelWriter`.
+        sheet_name : str, optional
+            Name of sheet that will have the codelist. If *None*, use the codelist name.
+        sort_by_code : bool, optional
+            Sort the codelist before exporting to file.
+        **kwargs
+            Passed to :class:`pandas.ExcelWriter` (if *excel_writer* is path-like).
+        """
+        # TODO write all dimensions to the file
+        self.variable.to_excel(excel_writer, sheet_name, sort_by_code, **kwargs)

tests/data/meta/allowed_values_2.yaml

@@ -0,0 +1,4 @@
+- Meta cat with boolean values:
+  allowed_values: [True, False]
+- Another category with str values:
+  allowed_values: ['ABC']

tests/data/meta/meta_indicators_allowed_values.yaml

@@ -0,0 +1,4 @@
+- Meta category with boolean values:
+  allowed_values: [True, False]
+- Meta cat with int values:
+  allowed_values: [1, 2, 3]