mrio-toolbox 1.0.0__py3-none-any.whl → 1.1.1__py3-none-any.whl

mrio_toolbox/__init__.py

@@ -1,5 +1,21 @@
+"""
+The MRIO toolbox module provides several submodules with different functionalities: 
+
+- `mrio_toolbox.mrio`: Contains the MRIO class for handling multi-regional input-output data.
+- `mrio_toolbox._parts`: Contains the Part and Axe classes for managing parts of MRIO data.
+- `mrio_toolbox.extractors`: Provides functions to extract raw MRIO data.
+- 'mrio_toolbox._msm': Contains the multi-scale mapping algorithm for mapping PRIMAP data into an MRIO
+- `mrio_toolbox._utils`: Contains utility functions for MRIO loading, saving and converting MRIO data to different formats.
+
+"""
+
 from mrio_toolbox.mrio import MRIO
 from mrio_toolbox._parts._Part import Part,load_part
+from mrio_toolbox.extractors import extract_MRIO
+from mrio_toolbox.extractors import download_MRIO
 
-__all__ = ["MRIO","load_part",
-           "Part"]
+__all__ = ["MRIO",
+           "load_part",
+           "Part",
+           "extract_MRIO",
+           "download_MRIO"]

mrio_toolbox/_parts/_Axe.py

@@ -11,41 +11,93 @@ from copy import deepcopy
 
 log = logging.getLogger(__name__)
 class Axe:
+    """
+    Representation of an Axe object.
+
+    An Axe holds the labels and dimensions for an MRIO Part. Axes are used 
+    to slice MRIO Parts based on labels or indices and support multi-level 
+    indexing and groupings.
+
+    Instance variables
+    ------------------
+    labels : dict
+        Dictionary of labels for each level of the Axe.
+    levels : int
+        Number of levels in the Axe.
+    dims : list of int
+        Number of labels for each level.
+    dimensions : list of str
+        Keys of the labels dictionary, representing the dimensions of the Axe.
+    groupings : dict
+        Groupings of the labels for each level of the Axe.
+    mappings : dict
+        Mappings used to convert grouping labels into indices.
+    multipliers : dict
+        Multipliers used to convert labels into indices.
+    name : str
+        Name of the Axe.
+
+    Methods
+    -------
+    set_labels(labels):
+        Set the labels of the Axe.
+    update_multipliers():
+        Update the multipliers used to convert labels into indices.
+    squeeze():
+        Remove levels with only one label.
+    swap_levels(level1, level2):
+        Swap the positions of two levels in the Axe.
+    label(as_index=False):
+        Generate the labels for the full axis.
+    isin(arg, level):
+        Check whether an element is in the labels of a given level.
+    derive_mappings(groupings=None):
+        Update the mappings of the Axe based on the groupings.
+    update_groupings(groupings=None):
+        Update the groupings of the Axe.
+    get(args, labels=False):
+        Get the indices corresponding to a selection on the Axe.
+    rename_labels(old, new):
+        Rename labels in the Axe.
+    replace_labels(name, labels):
+        Replace a given label in the Axe.
+    has_dim(dim):
+        Check whether a given dimension is in the Axe.
+    __getitem__(*args):
+        Indexing is passed to the `get` method.
+    __eq__(other):
+        Check equality between two Axe objects.
+    __len__():
+        Get the full label length of the Axe.
+    """    
+    
     def __init__(self,labels,groupings=None,
                  name=None):
-        """Define an Axe that holds the labels and dimensions for an MRIO part
-        
-        Axes hold the methods to slice MRIO Parts based on labels or indices.
+        """
+        Initialize an Axe object.
 
         Parameters
         ----------
         labels : dict or list of list of str
-            Dict of labels for each level of the Axe.
-            The levels are interpreted in the order of the keys.
-            If a list of list of str is passed, levels are set to 0,1,2...
+            Dictionary of labels for each level of the Axe. If a list of lists 
+            is passed, levels are set to 0, 1, 2, etc.
         groupings : dict, optional
-            Dict of groupings for each level of the Axe.
-            Grouping of labels into larger categories (e.g countries into zones).
-            If groupings contain references not in the labels, these are removed.
-        name : str
-            Name of the axis
-            If left empty, a name is generated automatically
-        
-        Attributes
-        ----------
-        labels : dict
-            Dict of labels for each level of the Axe.
-        levels : int
-            Number of levels in the Axe.
-        dims : list of int
-            Number of labels for each level.
-        dimensions : list of str
-            Keys of the labels dict.
-        
-        Main methods
-        ------------
-        label : Generate the labels for the full axis
-        get : Get the indices of a selection on the Axe
+            Dictionary of groupings for each level of the Axe. Groupings define 
+            how labels are grouped into larger categories (e.g., countries into zones).
+            If not provided, groupings are set to the identity.
+        name : str, optional
+            Name of the Axe. If not provided, a name is generated automatically 
+            based on the dimensions.
+
+        Raises
+        ------
+        TypeError
+            If the provided labels are not a dictionary or a list of lists.
+
+        Notes
+        -----
+        The `labels` parameter defines the structure of the Axe, while the 
+        `groupings` parameter allows grouping labels into higher-level categories.
         """
         if isinstance(labels,dict):
             self.labels = labels
@@ -66,6 +118,7 @@ class Axe:
             str(dim) for dim in self.labels.keys()
         ] #Dimensions of the Axe
         #Dimensions also save the order of the levels
+        self.ndim = len(self.dims)
         self.update_multipliers()
         if groupings is None:
             self.groupings = {i:{} for i in self.dimensions}
@@ -102,6 +155,7 @@ class Axe:
         self.levels = len(self.labels)
         self.dims = [len(dim) for dim in self.labels.values()]
         self.dimensions = list(self.labels.keys())
+        self.ndim = len(self.dims)
 
     def update_multipliers(self):
         """
@@ -125,6 +179,7 @@ class Axe:
         self.levels = len(self.labels)
         self.dims = [len(dim) for dim in self.labels.values()]
         self.dimensions = list(self.labels.keys())
+        self.ndim = len(self.dims)
         
 
     def swap_levels(self,level1,level2):
@@ -299,11 +354,12 @@ class Axe:
         return [sum(arg) for arg in itertools.product(*sel)]
     
     def get_labels(self):
-        """Get the labels of the Axe"""
-        labels = []
-        for key in self.dimensions:
-            labels.append(self.labels[key])
-        return labels
+        """Get the labels of the Axe as a dict"""
+        return {key:self.labels[key] for key in self.dimensions}
+    
+    def get_groupings(self):
+        """Get the groupings of the Axe"""
+        return self.groupings
     
     def get_labs(self,args):
         """Extract the labels corresponding to a given selection of multiple levels
@@ -433,12 +489,14 @@ class Axe:
         """
         if old not in self.labels.keys():
             raise IndexError(f"Label {old} not in the Axe")
-        self.labels[new] = self.labels.pop(old)
-        self.mappings[new] = self.mappings.pop(old)
+        self.labels = { (new if key == old else key): val 
+                       for key, val in self.labels.items()}
+        self.mappints = { (new if key == old else key): val 
+                       for key, val in self.mappings.items()}
         self.dimensions = list(self.labels.keys())
         self.update_multipliers()
         
-    def replace_label(self,name,labels):
+    def replace_labels(self,name,labels):
         """
         Replace a given label
 
@@ -450,7 +508,7 @@ class Axe:
             New labels
         """
         self.labels.update(labels)
-        if name != labels.keys()[0]:
+        if name != list(labels.keys())[0]:
             self.labels.pop(name)
             self.dimensions = list(self.labels.keys())
             self.mappings[labels.keys()[0]] = self.mappings.pop(name)