finished draft for explore notebook

doc/source/notebooks/explore.py

@@ -73,9 +73,145 @@
 mrio.emissions.get_regions()
 
 
+# %% [markdown]
+# The satellite accounts also have a special method to get index (rows) of the acccounts.
+
+# %%
+mrio.emissions.get_rows()
+
+# %% [markdown]
+## Searching through the MRIO
+
+# %% [markdown]
+# Several methods are available to search through the whole MRIO.
+# These generally accept [regular expressions](https://docs.python.org/3/howto/regex.html) as search terms.
+
+# %% [markdown]
+# The most general method is 'find'. This can be used for a quick overview where a specific term appears in the MRIO.
+
+
+# %%
+mrio.find('air')
+
+# %%
+mrio.find("trade")
+
+# %% [markdown]
+# Not that 'find' (and all other search methods) a case sensitive.
+# Do make a case insensitive search, add the regular expression flag `(?i)` to the search term.
+
+# %%
+mrio.find('value')
+
+# %%
+mrio.find('(?i)value')
+
+# %% [markdown]
+# ## Specific search methods: contains, match, fullmatch, 
+
+# %% [markdown]
+# The MRIO class also contains a set of specific regular expresion search methods, mirroring the 'contains', 'match' and 'fullmatch' 
+# methods of the pandas DataFrame str column type. See the pandas documentation for details, in short:
+#
+#   -. 'contains' looks for a match anywhere in the string
+#   -. 'match' looks for a match at the beginning of the string
+#   -. 'fullmatch' looks for a match of the whole string
+#
+# These methods are available for all index columns of the MRIO and have a similar signature:
+#
+#   1. As for 'find_all', the search term is case sensitive. To make it case insensitive, add the regular expression flag `(?i)` to the search term.
+#   2. The search term can be passed to the keyword argument 'find_all' or as the first positional argument to search in all index levels.
+#   3. Alternativels, the search term can be passed to the keyword argument with the level name to search only in that index level.
+#
+# The following examples show how to use these methods.
+
+# %%
+mrio.contains(find_all = 'ad')
+mrio.contains('ad')
+
+# %%
+mrio.match('ad')
+
+# %%
+mrio.match('trad')
+
+# %%
+mrio.fullmatch('trad')
+
+# %%
+mrio.fullmatch('trade')
+
+# %%
+mrio.fullmatch('(?i).*AD.*')
+
+# %% [markdown]
+# For the rest of the notebook, we will do the examples with the 'contains' method, but the same applies to the other methods.
 
+# %% [markdown]
+# To search only at one specific level, pass the search term to the keyword argument with the level name.
+
+# %%
+mrio.contains(region='trade')
+
+# %%
+mrio.contains(sector='trade')
+
+# %% [markdown]
+# And of course, the method are also available for the satellite accounts.
+
+# %%
+mrio.emissions.contains(compartment='air')
+
+# %% [markdown]
+# Passing a non-existing level to the keyword argument is silently ignored.
+
+# %%
+mrio.factor_inputs.contains(compartment='trade')
+
+# %% [markdown]
+# This allows to search for terms that are only in some index levels.
+# Locially, this is an 'or' search.
+# %%
+mrio.factor_inputs.contains(compartment='air', inputtype="Value")
+
+# %% [markdown]
+# But note, that if both levels exist, both must match (so it becomes a logical 'and').
+
+# %%
+mrio.emissions.contains(stressor='emission', compartment='air')
+
+# %% [markdown]
+# ## Search through all extensions
+
+# %% [markdown]
+# All three search methods are also available to loop through all extensions of the MRIO.
 
+# %%
+mrio.extension_contains(stressor='emission', compartment='air')
 
+# %% [markdown]
+# If only a subset of extensions should be searched, pass the extension names to the keyword argument 'extensions'.
 
+# %% [markdown]
+# ## Generic search method for any dataframe index
+
+# %% [markdown]
+# Internally, the class methods 'contains', 'match' and 'fullmatch' all the 
+# 'index_contains', 'index_match' and 'index_fullmatch' methods of ioutil module.
+# This function can be used to search through index of any pandas DataFrame.
 
+# %%
+df = mrio.Y
+
+# %% [markdown]
+# Depending if a dataframe or an index is passed, the return is either the dataframe or the index.
+
+# %%
+pymrio.index_contains(df, 'trade')
+
+# %%
+pymrio.index_contains(df.index, 'trade')
+
+# %%
+pymrio.index_fullmatch(df, region='reg[2,4]', sector='m.*')