started with docs for exploring mrios

doc/source/notebooks/advanced_group_stressors.ipynb

@@ -1431,7 +1431,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -1445,7 +1445,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.5"
+   "version": "3.10.12"
   }
  },
  "nbformat": 4,

doc/source/notebooks/explore.ipynb

@@ -0,0 +1,55 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "444a77e7-8a6f-44c1-bdac-b7f1e0b052e8",
+   "metadata": {
+    "tags": []
+   },
+   "source": [
+    "# Exploring MRIOs with Pymrio"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "7a8d7b7a-1d21-4cea-b7bf-578ac1b40679",
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "import pymrio"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5ac4addd-0a85-4b49-8f95-48bc25a24366",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

doc/source/notebooks/explore.py

@@ -0,0 +1,81 @@
+# ---
+# jupyter:
+#   jupytext:
+#     text_representation:
+#       extension: .py
+#       format_name: percent
+#       format_version: '1.3'
+#       jupytext_version: 1.15.0
+#   kernelspec:
+#     display_name: Python 3 (ipykernel)
+#     language: python
+#     name: python3
+# ---
+
+# %% [markdown]
+# # Exploring MRIOs with Pymrio
+
+# %% [markdown]
+# The first step when working with a new MRIO data set is to familiarize yourself with the data. 
+# This notebook shows how to use the `pymrio` package to explore the data. 
+# We use the test data set that is included in the `pymrio` package. 
+# This is a completely artificial, very small MRIO. 
+# It is not meant to be realistic, but it is useful for developing, testing and learning.
+
+
+# %% [markdown]
+# First we import the required packages:
+
+# %%
+import pymrio
+
+# %% [markdown]
+# We can now load the test data set with the `load_test` function. We can call 
+# the MRIO whatever we want, here we use mrio.
+
+# %%
+mrio = pymrio.load_test()
+
+# %% [markdown]
+# We can get some first information about the MRIO by printing it.
+
+# %%
+print(mrio)
+
+# %% [markdown]
+# This tells us what the MRIO data we just loaded contains.
+# We find a Z and Y matrix, some unit information and two satellite accounts, factor_inputs and emissions.
+
+# %% [markdown]
+# To get more specific data we can ask pymrio for regions, sectors, products, etc.
+
+# %%
+mrio.name
+
+# %%
+mrio.get_regions()
+
+# %%
+mrio.get_sectors()
+
+# %%
+mrio.get_Y_categories()
+
+# %% [markdown]
+# The same methods can be used to explore one of the satellite accounts.
+
+# %%
+print(mrio.emissions)
+
+# %%
+mrio.emissions.name
+# %%
+mrio.emissions.get_regions()
+
+
+
+
+
+
+
+

doc/source/notebooks/jupytext.toml

@@ -0,0 +1,2 @@
+# Pair ipynb notebooks to py:percent text notebooks
+formats = "ipynb,py:percent"

doc/source/notebooks/metadata.ipynb

@@ -7,6 +7,13 @@
     "# Metadata and change recording"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "**DEPRECATED**: this will be removed and changed to loguru soon"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -437,7 +444,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -451,7 +458,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.5"
+   "version": "3.10.12"
   }
  },
  "nbformat": 4,

doc/source/notebooks/metadata.py

@@ -0,0 +1,91 @@
+# ---
+# jupyter:
+#   jupytext:
+#     text_representation:
+#       extension: .py
+#       format_name: percent
+#       format_version: '1.3'
+#       jupytext_version: 1.15.0
+#   kernelspec:
+#     display_name: Python 3 (ipykernel)
+#     language: python
+#     name: python3
+# ---
+
+# %% [markdown]
+# # Metadata and change recording
+
+# %% [markdown]
+# **DEPRECATED**: this will be removed and changed to loguru soon
+
+# %% [markdown]
+# Each pymrio core system object contains a field 'meta' which stores meta data as well as changes to the MRIO system. This data is stored as json file in the root of a saved MRIO data and accessible through the attribute '.meta':
+
+# %%
+import pymrio
+
+io = pymrio.load_test()
+
+# %%
+io.meta
+
+# %%
+io.meta("Loaded the pymrio test system")
+
+# %% [markdown]
+# We can now do several steps to modify the system, for example:
+
+# %%
+io.calc_all()
+io.aggregate(region_agg="global")
+
+# %%
+io.meta
+
+# %% [markdown]
+# Notes can added at any time:
+
+# %%
+io.meta.note("First round of calculations finished")
+
+# %%
+io.meta
+
+# %% [markdown]
+# In addition, all file io operations are recorde in the meta data:
+
+# %%
+io.save_all("/tmp/foo")
+
+# %%
+io_new = pymrio.load_all("/tmp/foo")
+
+# %%
+io_new.meta
+
+# %% [markdown]
+# The top level meta data can be changed as well. These changes will also be recorded in the history:
+
+# %%
+io_new.meta.change_meta("Version", "v2")
+
+# %%
+io_new.meta
+
+# %% [markdown]
+# To get the full history list, use:
+
+# %%
+io_new.meta.history
+
+# %% [markdown]
+# This can be restricted to one of the history types by:
+
+# %%
+io_new.meta.modification_history
+
+# %% [markdown]
+# or
+
+# %%
+io_new.meta.note_history

pymrio/core/mriosystem.py

@@ -523,7 +523,7 @@ def get_DataFrame(self, data=False, with_unit=True, with_population=True):
 
     @property
     def empty(self):
-        """ True, if all dataframes of the system are empty"""
+        """True, if all dataframes of the system are empty"""
         for df in self.get_DataFrame(data=True):
             if len(df) > 0:
                 return False
@@ -1645,7 +1645,8 @@ def extract(self, index, dataframes=None, return_as_extension=False):
         else:
             if not all(elem in self.get_DataFrame() for elem in dataframes):
                 logging.warning(
-                    f"Not all requested dataframes are available in {self.name}")
+                    f"Not all requested dataframes are available in {self.name}"
+                )
             dataframes = [elem for elem in dataframes if elem in self.get_DataFrame()]
 
         for dfname in dataframes:
@@ -2380,10 +2381,9 @@ def extension_contains(self, find_all=None, extensions=None, **kwargs):
             extensions, method="contains", find_all=find_all, **kwargs
         )
 
-    def extension_extract(self, index_dict, 
-                          dataframes=None, 
-                          include_empty=False, 
-                          return_type='dataframes'):
+    def extension_extract(
+        self, index_dict, dataframes=None, include_empty=False, return_type="dataframes"
+    ):
         """Get a dict of extension index dicts which match a search pattern
 
         This calls the extension.extract for all extensions.
@@ -2418,20 +2418,22 @@ def extension_extract(self, index_dict,
             the matched rows as values
 
         """
-        if return_type.lower() in ['dataframes', 'df']:
+        if return_type.lower() in ["dataframes", "df"]:
             return_as_extension = False
         else:
             return_as_extension = True
-        
-        if return_type.lower() not in ['dataframes', 'df', 'ext', 'extension']:
+
+        if return_type.lower() not in ["dataframes", "df", "ext", "extension"]:
             ext_name = return_type
         else:
             ext_name = None
 
-
         extracts = self._apply_extension_method(
-            extensions=None, method="extract", index=index_dict, 
-            dataframes=dataframes, return_as_extension=return_as_extension
+            extensions=None,
+            method="extract",
+            index=index_dict,
+            dataframes=dataframes,
+            return_as_extension=return_as_extension,
         )
 
         if (not include_empty) or ext_name:
@@ -2457,8 +2459,7 @@ def extension_extract(self, index_dict,
 
     # CONT: 1) write tests for this, write test for extraction and new extension
     # CONT: 2) write doc for contains, match, - function, extension function and top-level function
-    # show a new extension can be built 
-
+    # show a new extension can be built
 
     def _apply_extension_method(self, extensions, method, *args, **kwargs):
         """Apply a method to a list of extensions