Merge pull request #236 from dgdekoning/bwutils-tweaks

Bwutils documentation and refactoring

activity_browser/app/bwutils/metadata.py

@@ -8,31 +8,51 @@
 
 
 class MetaDataStore(object):
-    """
-A container for metadata for technosphere and biosphere activities during an AB session.
+    """A container for technosphere and biosphere metadata during an AB session.
+
+    This is to prevent multiple time-expensive repetitions such as the code
+    below at various places throughout the AB:
+
+    .. code-block:: python
+        meta_data = list()  # or whatever container
+        for ds in bw.Database(name):
+            meta_data.append([ds[field] for field in fields])
 
-This is to prevent multiple time-expensive repetitions such as the code below at various places throughout the AB:
+    Instead, this data store features a dataframe that contains all metadata
+    and can be indexed by (activity or biosphere key).
+    The columns feature the metadata.
 
-.. code-block:: python
-    meta_data = list()  # or whatever container
-    for ds in bw.Database(name):
-        meta_data.append([ds[field] for field in fields])
+    Properties
+    ----------
+    index
 
-Instead, this data store features a dataframe that contains all metadata and can be indexed by (activity or biosphere key). The columns feature the metadata.
     """
     def __init__(self):
         self.dataframe = pd.DataFrame()
         self.databases = set()
-        self.connect_signals()
+        self._connect_signals()
         self.unpacked_columns = {}
 
-    def connect_signals(self):
+    def _connect_signals(self):
         signals.project_selected.connect(self.reset_metadata)
         signals.metadata_changed.connect(self.update_metadata)
 
     def add_metadata(self, db_names_list):
-        """Get metadata in form of a Pandas DataFrame for biosphere and technosphere databases
-        for tables and additional aggregation.
+        """"Include data from the brightway databases.
+
+        Get metadata in form of a Pandas DataFrame for biosphere and
+        technosphere databases for tables and additional aggregation.
+
+        Parameters
+        ----------
+        db_names_list : list
+            Contains the names of all databases to add to the MetaDataStore
+
+        Raises
+        ------
+        ValueError
+            If a database name does not exist in `brightway.databases`
+
         """
         dfs = list()
         dfs.append(self.dataframe)
@@ -68,10 +88,16 @@ def add_metadata(self, db_names_list):
 
     def update_metadata(self, key):
         """Update metadata when an activity has changed.
+
         Three situations:
         1. An activity has been deleted.
         2. Activity data has been modified.
         3. An activity has been added.
+
+        Parameters
+        ----------
+        key : str
+            The specific activity to update in the MetaDataStore
         """
         try:
             act = bw.get_activity(key)  # if this does not work, it has been deleted (see except:).
@@ -108,6 +134,29 @@ def reset_metadata(self):
         self.dataframe = pd.DataFrame()
         self.databases = set()
 
+    def get_existing_fields(self, field_list):
+        """Return a list of fieldnames that exist in the current dataframe.
+        """
+        return [fn for fn in field_list if fn in self.dataframe.columns]
+
+    def get_metadata(self, keys, columns):
+        """Return a slice of the dataframe matching row and column identifiers.
+        """
+        return self.dataframe.loc[keys][columns]
+
+    def get_database_metadata(self, db_name):
+        """Return a slice of the dataframe matching the database.
+        """
+        return self.dataframe[self.dataframe['database'] == db_name]
+
+    @property
+    def index(self):
+        """Returns the (multi-) index of the MetaDataStore.
+
+        This allows us to 'hide' the dataframe object in de AB_metadata
+        """
+        return self.dataframe.index
+
     def unpack_tuple_column(self, colname, new_colnames=None):
         """Takes the given column in the dataframe and unpack it.
 
@@ -152,4 +201,4 @@ def unpack_tuple_column(self, colname, new_colnames=None):
         self.unpacked_columns[colname] = new_colnames
 
 
-AB_metadata = MetaDataStore()
+AB_metadata = MetaDataStore()