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

mrio_toolbox/mrio.py

@@ -1,9 +1,8 @@
 # -*- coding: utf-8 -*-
 """
-Created on Thu Mar 30 10:42:23 2023
-
-Representation of economic MRIO tables
+This module provides the MRIO class.
 
+Created on Thu Mar 30 10:42:23 2023
 @author: beaufils
 """
 
@@ -16,6 +15,7 @@ from mrio_toolbox._parts import Part
 from mrio_toolbox.utils import converters
 from mrio_toolbox.utils.loaders import make_loader
 from mrio_toolbox.utils.savers import save_mrio_to_folder,save_to_nc
+from mrio_toolbox.utils.formatting import formatter
 
 log = logging.getLogger(__name__)
 
@@ -23,72 +23,105 @@ class MRIO:
     """
     Representation of an MRIO table
 
-    An MRIO table holds a collection of Parts, each representing a different
-    aspect of the table (inter-industry matrix, final demand, etc.)
-    The MRIO instance allows to perform basic operations on the table.
+    An MRIO table holds a collection of Parts, each representing a different aspect 
+    of the table (e.g., inter-industry matrix, final demand, satellite accounts, etc).
+    The MRIO instance allows performing basic operations on the table, such as
+    loading parts, setting groupings, filtering, aggregating, and saving data.
 
     Instance variables
-    -------------------
+    ------------------
     metadata : dict
-        Dictionnary storing the metadata
+        Dictionary storing the metadata of the MRIO table.
     labels : dict
-        Labels of the table parts:
-            list of countries
-            list of sectors
+        Labels of the table parts, including:
+            - List of countries
+            - List of sectors
     groupings : dict
-        Groupings of the MRIO table.
-        Groupings are used to group labels into larger categories 
-        (e.g countries into zones, sectors in aggregate sectors).
-        Groupings have in principle no impact on the resolution of the table
-        but can be used for visualization or aggregation purposes.
+        Groupings of the MRIO table. Groupings are used to group labels into 
+        larger categories (e.g., countries into zones, sectors into aggregate 
+        sectors). These groupings are primarily used for visualization or 
+        aggregation purposes.
     c : int
-        Number of countries in the table
+        Number of countries in the table.
     s : int
-        Number of sectors in the table
+        Number of sectors in the table.
     parts : dict of Part objects
-        
-        
+        Dictionary containing the different parts of the MRIO table.
+
     Methods
-    -----------
-    load_parts(parts,year) :
-        Load new parts
-    load_zones(name) : 
-        load new zones
-    rename_zone(zone,name) :
-        rename a zone
-    modify_zone()
-    load_extension(extension):
-        Load a new MRIO extension.
-    group_y():
-        Aggregated final demand by zone.
-    extract_zone(part,zone):
-        Extract a given zone from a given part of the MRIO table.
-    sel(index):
-        Returns the slice containing the indices of all sectors of a country.
+    -------
+    __init__(**kwargs):
+        Initialize an MRIO instance from a file or explicit parameters.
+    load_part(update_part=True, standalone=False, **kwargs):
+        Load a Part object into the MRIO table.
+    set_groupings(groupings=None):
+        Set the groupings of the MRIO table.
+    filter(threshold, fill_value=0):
+        Filter the MRIO table by removing values below a specified threshold.
+    add_part(part, name=None, update_part=True):
+        Add a Part object to the MRIO table.
+    new_part(data=None, name="part", dimensions=None, fill_value=0.0, **kwargs):
+        Create a new Part object from data or dimensions.
+    add_dimensions(dimensions):
+        Add new dimensions to the MRIO table.
+    add_labels(new_indices, dimension, fill_value=0.0):
+        Add items to a label of the MRIO instance.
+    replace_labels(name, new_labels):
+        Replace labels for one or more dimensions in all MRIO parts.
+    rename_dimensions(old_names, new_names):
+        Rename the names of the dimensions in the MRIO table.
+    aggregate(on="sectors"):
+        Aggregate the MRIO table on a given dimension.
+    has_neg(parts=None):
+        Check whether some parts of the MRIO table have negative values.
+    copy():
+        Create a copy of the MRIO object.
+    save(file, name=None, extension="npy", overwrite=False, **kwargs):
+        Save the current MRIO instance to a file or folder.
+    to_xarray():
+        Convert the MRIO instance to an xarray Dataset.
+
+    Notes
+    -----
+    This class provides a comprehensive interface for working with MRIO tables,
+    including loading, modifying, and saving data, as well as performing 
+    operations like filtering and aggregation.
     """
+    
     def __init__(self,**kwargs):
         """
-        Initialize an MRIO instance
+        Initialize an MRIO instance.
 
-        There are two ways to initialize an MRIO instance:
-            - from a .nc file
-            - from explicit parameters
-        
-        If created from a .nc file, only the "file" parameter is required, with the path to the file.
-        Loading an MRIO from explicit parameters requires at least a path to the data and the labels.
-        
-        You can also provide the path to a .yaml file containing the loading instructions,
-        using the "file" parameter.
+        There are multiple ways to initialize an MRIO instance:
+            - From a `.nc` file: Provide the "file" parameter with the path to the file.
+            - From explicit parameters: Provide the data, labels, and metadata explicitly.
+            - From a `.yaml` file: Provide the "file" parameter with the path to a `.yaml` file 
+              containing loading instructions.
 
-        Note that the "data" parameter is reserved for setting an MRIO instance from a dictionary.
-        It is intended for internal use only.
+        If no arguments are provided, an empty MRIO instance is created.
 
         Parameters
         ----------
         file : str, optional
-            Path to the file to load the MRIO table from.
-            If a .yaml file is provided, the file is interpreted as loading instructions.
+            Path to the file to load the MRIO table from. If a `.yaml` file is provided, 
+            it is interpreted as loading instructions.
+        data : dict, xarray.DataArray, xarray.Dataset, or pandas.DataFrame, optional
+            Data to initialize the MRIO instance. If provided, the instance is created 
+            from this data.
+        kwargs : dict
+            Additional parameters for initializing the MRIO instance.
+
+        Raises
+        ------
+        ValueError
+            If the provided data type is not supported for initializing the MRIO instance.
+            
+        Notes
+        -----
+        The "data" parameter is reserved for setting an MRIO instance from a dictionary.
+        It is intended for internal use only.
         """
+        
         if not kwargs:
             #Create an empty MRIO instance
             kwargs = {
@@ -135,12 +168,9 @@ class MRIO:
 
         #Initialize the parts
         self.parts = dict()
-        available_parts = kwargs.get(
-            "parts",
-            self.loader.available_parts(
+        available_parts = self.loader.available_parts(
                 extension = kwargs.get("extension",None)
             )
-                             )
         
         to_load = {part:part for part in available_parts}
         if "part_settings" in self.loader.__dict__ and bool(self.loader.part_settings):
@@ -230,14 +260,16 @@ class MRIO:
             part.set_labels(part_labels)
 
     def _get_labels(self,l):
-        """Find the labels fitting an axis with a given shape
+        """
+        Find the labels fitting an axis with a given shape
         
         Available labels:
-            countries and sectors
-            countries
-            zones and sectors
-            zones
-            sectors
+        
+            - countries and sectors
+            - countries
+            - zones and sectors
+            - zones
+            - sectors
             
         If no fitting label is found, data are labelled numerically
 
@@ -289,8 +321,10 @@ class MRIO:
             Groupings of the MRIO table.
             The default is None.
             If None, the groupings are set to the identity.
-            Groupings should be provided as a dict of dict:
+            Groupings should be provided as a dict of dict::
+            
                 {dimension : {group : [items]}}
+                
             where dimension is the name of the label to group,
             group is the name of the group,
             and items is a list of items to group.
@@ -301,16 +335,16 @@ class MRIO:
         for key in groupings.keys():
             labels = self.labels[key]
             covered = []
-            for group in groupings[key]:
-                for item in groupings[key][group]:
-                    if item not in self.labels[key]:
+            for group in list(groupings[key]):
+                for item in list(groupings[key][group]):
+                    if item not in labels:
                         log.warning(
                             f"Item {item} not found in {key} labels"
                             )
                         groupings[key][group].remove(item)
                     else:
                         covered.append(item)
-                if len(group) == 0:
+                if len(groupings[key][group]) == 0:
                     log.warning(f"Group {group} is empty")
                     groupings[key].pop(group)
             for item in labels:
@@ -395,9 +429,11 @@ class MRIO:
         dimensions or labels : list of str, list of ints, str, list of dicts, optional
             Labels of the Part. 
             Either of these formats are accepted:
-                Dictionary of explicit labels for each axis
-                List of explicit labels for each axis
-                List of existing dimension names
+            
+                - Dictionary of explicit labels for each axis
+                - List of explicit labels for each axis
+                - List of existing dimension names
+                
             If None, the labels are inferred from the data shape.
         multiplier : str, optional
             multiplier of the data. The default is None.
@@ -420,6 +456,8 @@ class MRIO:
                     return {dimensions:self.labels[dimensions]}
                 if dimensions in self.groupings.keys():
                     return {dimensions:list(self.groupings[dimensions])}
+                log.warning(f"Dimension {dimensions} not found in labels or groupings\n"+\
+                            " Available dimensions are "+str(self.labels.keys()))
                 raise ValueError(f"Invalid dimension {dimensions}")
             if isinstance(dimensions,int):
                 #Try to infer the dimension from the length of the data
@@ -494,8 +532,34 @@ class MRIO:
         """
         for dimension in dimensions.keys():
             log.info("Add dimension "+dimension+" to MRIO table")
+            # check whether the dimension is already in the labels
+            if dimension in self.labels.keys():
+                log.info(f"Dimension {dimension} already exists in MRIO labels")
+                if dimensions[dimension] != self.labels[dimension]:
+                    log.warning(f"There already exist different or differently ordered labels for dimension '{dimension}' in the MRIO labels. "+ 
+                                "You are now overwriting them which leads to inconsistent labels in the parts of your MRIO table!")
+            
+            if isinstance(dimensions[dimension],str):
+                #For single item dimensions, convert to list
+                dimensions[dimension] = [dimensions[dimension]]
             self.labels[dimension] = dimensions[dimension]
 
+    def check_label_consistency(self):
+        """
+        Check whether the labels of of all parts of the MRIO table are consistent.
+        """
+        
+        for part in self.parts.keys():
+            for key, labels in self.parts[part].labels.items():
+                if key in self.labels.keys():
+                    if labels != self.labels[key]: 
+                        log.warning(f"Labels for dimension'{key}' in part '{part}' are inconsistent with MRIO labels")
+                        return False
+                else: 
+                    log.warning(f"Label {key} not found in MRIO labels")
+                    return False
+        return True
+    
     def add_labels(self,new_indices,dimension,
                    fill_value=0.0):
         """
@@ -530,28 +594,59 @@ class MRIO:
 
     def replace_labels(self,name,new_labels):
         """
-        Replace labels in all MRIO parts
+        Replace labels for one or more dimensions in all MRIO parts. 
+
+        Parameters
+        ----------
+        name : str or list of str
+            Name of the dimension for which the labels should be replaced 
+        new_labels : list of str or dict of list of str
+            New labels for given dimension in the labels dictionary.
+        """
+        log.info(f"Replace labels for {name}")
+        if isinstance(name,str):
+            self._replace_individual_labels(name = name, new_labels = new_labels)
+        elif isinstance(name,list):
+            for dimension in name:
+                if isinstance(new_labels,list):
+                    raise ValueError("You provided multiple dimensions but only one set of new labels.")
+                elif isinstance(new_labels,dict):
+                    new_labels = new_labels[dimension]
+                else: 
+                    raise TypeError(f"Invalid type for new labels: {type(new_labels)}")
+                self._replace_individual_labels(dimension,new_labels)
+         
+    def _replace_individual_labels(self,name, new_labels): # check for usages and update them
+        """
+        Replace labels for one dimension in all MRIO parts. 
 
         Parameters
         ----------
-        names : str
-            Name of the labels 
-        new_labels : dict of str:list of str
-            Description of the new labels to use.
+        name : str
+            Name of the labels to replace. Usually this is 'countries', 'sectors', 'va_labs' or 'y_labs'
+        new_labels : list of str
+            New labels for given name in the label dictionary.
         """
         log.info(f"Replace labels for {name}")
+        if name not in self.labels.keys():
+            log.warning(f"Label {name} is not in MRIO labels and cannot be replaced.")
+            return
         for part in self.parts.keys():
-            self.parts[part] = self.parts[part].replace_labels(name,new_labels)
-        if name != new_labels.keys():
-            self.labels.update(new_labels)
-            self.labels.pop(name)
-            if name in self.groupings.keys():
-                self.groupings.pop(name)
+            self.parts[part].replace_labels(name, new_labels)
         self.loader.set_labels(self.labels)
+        self.labels[name] = new_labels
+        
+        if name in self.groupings.keys():
+            log.warning("Groupings for all dimensions are reset to identity, because the labels have changed.\n \
+                        Please update the groupings manually if needed.")
+            self.set_groupings(groupings=None)
 
-    def rename_labels(self,old_names,new_names):
+    def rename_dimensions(self,old_names,new_names):
         """
-        Rename labels for the MRIO instance
+        Rename the names of the dimensions.
+        
+        The keys of the label dicts for the MRIO instance are renamed.
+        The content of the labels and the groupings is conserved. 
 
         Parameters
         ----------
@@ -566,16 +661,49 @@ class MRIO:
             new_names = [new_names]
         for old,new in zip(old_names,new_names):
             log.info(f"Rename label {old} to {new}")
-            if old not in self.labels.keys():
+            
+            if old in self.labels.keys():
+                self.labels = {new if key == old else key : value for key, value in self.labels.items()}
+            else:
                 log.warning(f"Label {old} is not in MRIO labels and cannot be renamed.")
                 continue
-            self.labels[new] = self.labels.pop(old)
             if old in self.groupings.keys():
-                self.groupings[new] = self.groupings.pop(old)
+                self.groupings = {new if key == old else key : value for key, value in self.groupings.items()}
             for part in self.parts.keys():
                 self.parts[part].rename_labels(old,new)
-            if old in self.labels.keys():
-                self.labels[new] = self.labels.pop(old)
+                
+    def reorder_data(self, new_labels):
+        """
+        Reorder the data of the MRIO instance based on new labels.
+
+        This method is used to reorder the data of the MRIO instance based on the new labels.
+        The new labels should be a dictionary with the same keys and items as the old mrio labels
+        but the keys and items can be in a different order. The data of the part is then reordered
+        to fit the new labels.
+
+        Parameters
+        ----------
+        new_labels : dict
+            New labels to use for reordering.
+        """
+        log.info("Reorder MRIO data with new labels")
+        old_labels = self.labels
+        if not isinstance(new_labels,dict):
+            raise TypeError(f"Invalid type for new labels: {type(new_labels)}. Expected a dict.")
+        if not set(new_labels.keys()).issubset(set(old_labels.keys())):
+            raise ValueError("You are trying to reorder data for dimensions that are not present in your MRIO instance")
+        
+        for part in self.parts.keys():
+            new_part_labels = {}
+            for key, labels in new_labels.items():
+                if key in self.parts[part].labels.keys():
+                    new_part_labels[key] = labels
+            self.parts[part].reorder_data(new_part_labels)
+                    
+        for key in new_labels.keys():
+            self.replace_labels(key, new_labels[key])
+
+
 
     def aggregate(self,on="sectors"):
         """Aggregate the MRIO table on a given dimension
@@ -666,10 +794,10 @@ class MRIO:
         -------
         bool
         """
-        if parts is None:
-            parts = "all"
-        elif isinstance(parts,str):
+        if isinstance(parts,str):
             parts = [parts]
+        elif parts is None:
+            parts = self.parts.keys()
         for part in parts:
             if self.parts[part].hasneg():
                 return True
@@ -680,9 +808,9 @@ class MRIO:
         return MRIO(data=self.__dict__)
     
     def save(self,
-             file,
+             file=None,
              name=None,
-             extension = "npy",
+             extension = ".nc",
              overwrite=False,
              **kwargs):
         """
@@ -693,6 +821,7 @@ class MRIO:
             - .csv
             - .txt
             - .xlsx
+            
         Labels are saved as .txt files and metadata as a .yaml file.
 
         Otherwise the MRIO instance is saved as a .nc file.
@@ -712,9 +841,13 @@ class MRIO:
         kwargs : dict
             Additional arguments to pass to the saver.
         """
+        if file is None:
+            if file is None:
+                name = self.metadata.get("name","mrio")
+            file = name
         file_extension = os.path.splitext(file)[1]
         if file_extension == "" and extension == ".nc":
-            file = file+".nc"
+            file = os.path.join(file+".nc")
             file_extension = ".nc"
         if file_extension == "":
             #If the file is a folder, save in folder
@@ -728,7 +861,7 @@ class MRIO:
                 )
         elif file_extension == ".nc":
             #If the file is a .nc, save the tables
-            save_to_nc(self,file,name,overwrite)
+            save_to_nc(self,file,overwrite,**kwargs)
         else:
             raise NotImplementedError(f"Cannot save MRIO in {file_extension} format")
     
@@ -736,4 +869,31 @@ class MRIO:
         """
         Convert the MRIO instance to an xarray Dataset
         """
-        return converters.xarray.to_DataSet(self)
+        return converters.xarray.to_DataSet(self)
+    
+    def reallocate_negatives(self,**kwargs):
+        formatter.reallocate_negatives(self,**kwargs)
+
+    def adjust_intermediates(self,**kwargs):
+        formatter.adjust_intermediates(self,**kwargs)
+
+    def fill_empty_rows(self,**kwargs):
+        formatter.fill_empty_rows(self,**kwargs)
+
+    def balance_va(self,**kwargs):
+        formatter.balance_va(self,**kwargs)
+
+    def compute_technical_coefficients(self,**kwargs):
+        formatter.compute_technical_coefficients(self,**kwargs)
+
+    def compute_leontief(self,**kwargs):
+        formatter.compute_leontief(self,**kwargs)
+
+    def preprocess(self,**kwargs):
+        formatter.preprocess(self,**kwargs)
+
+    def rename_part(self,old_name,new_name):
+        formatter.rename_part(self,old_name,new_name)
+
+    def rename_parts(self,renaming_dict):
+        formatter.rename_parts(self,renaming_dict)

mrio_toolbox/msm/__init__.py

@@ -0,0 +1,6 @@
+"""
+This module provides the multi_scale_mapping function for mapping PRIMAP data into an MRIO.
+"""
+from .multi_scale_mapping import multi_scale_mapping
+
+__all__ = ["multi_scale_mapping"]