Clean-up exposing internal methods and attributes (#764)

IAMconsortium · Aug 21, 2023 · f8d0ca0 · f8d0ca0
1 parent 1044c28
commit f8d0ca0
Show file tree

Hide file tree

Showing 46 changed files with 485 additions and 405 deletions.
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -4,16 +4,22 @@ The next release must bump the major version number.
 
 ## API changes
 
-The column *exclude* of the `meta` attribute was refacored to a new attribute `exclude`.
+The column *exclude* of the `meta` indicators was moved to a new attribute `exclude`.
 All validation methods are refactored such that the argument `exclude_on_fail` changes
 this new attribute (see PR [#759](https://github.com/IAMconsortium/pyam/pull/759)).
 
 The term "exclude" is now an illegal column name for (timeseries) data and meta tables.
 When importing an xlsx file created with pyam < 2.0, which has an "exclude" column in
 "meta", that column is moved to the new exclude attribute with a log message.
 
+PR [#764](https://github.com/IAMconsortium/pyam/pull/764) implemented a more restrictive
+approach to exposing pyam-internals at the package level, requiring a more explicit
+import of these methods. For example, use `pyam.utils.to_list()`
+instead of `pyam.to_list()`.
+
 ## Individual updates
 
+- [#764](https://github.com/IAMconsortium/pyam/pull/764) Clean-up exposing internal methods and attributes
 - [#763](https://github.com/IAMconsortium/pyam/pull/763) Implement a fix against carrying over unused levels when initializing from an indexed pandas object
 - [#759](https://github.com/IAMconsortium/pyam/pull/759) Excise "exclude" column from meta and add a own attribute
 - [#747](https://github.com/IAMconsortium/pyam/pull/747) Drop support for Python 3.7

diff --git a/docs/api/compute.rst b/docs/api/compute.rst
@@ -1,4 +1,4 @@
-.. currentmodule:: pyam
+.. currentmodule:: pyam.compute
 
 Derived timeseries data
 =======================

diff --git a/docs/api/slice.rst b/docs/api/slice.rst
@@ -1,4 +1,4 @@
-.. currentmodule:: pyam
+.. currentmodule:: pyam.slice
 
 The **IamSlice** class
 ======================

diff --git a/docs/api/timeseries.rst b/docs/api/timeseries.rst
@@ -1,4 +1,4 @@
-.. currentmodule:: pyam
+.. currentmodule:: pyam.timeseries
 
 Timeseries functions
 ====================

diff --git a/docs/api/variables.rst b/docs/api/variables.rst
@@ -1,12 +1,11 @@
-.. currentmodule:: pyam
+.. currentmodule:: pyam.str
 
 Variables utilities
 ===================
 
-The **variable** dimension of the |pyam| data format implements
-implements a "semi-hierarchical" structure using the :code:`|` character
-(*pipe*, not l or i) to indicate the *depth*.
-Read the `data model documentation`_ for more information.
+The **variable** dimension of the |pyam| data format implements implements a
+"semi-hierarchical" structure using the :code:`|` character (*pipe*, not l or i)
+to indicate the *depth*. Read the `data model documentation`_ for more information.
 
 .. _`data model documentation`: ../data.html#the-variable-column
 
@@ -16,6 +15,8 @@ The package provides several functions to work with such strings.
 
 .. autofunction:: find_depth
 
+.. autofunction:: get_variable_components
+
 .. autofunction:: reduce_hierarchy
 
-.. autofunction:: get_variable_components
+.. autofunction:: is_str
diff --git a/docs/examples/plot_scatter.py b/docs/examples/plot_scatter.py
@@ -57,7 +57,7 @@
 )
 
 df.set_meta(
-    meta=co2.apply(pyam.cumulative, first_year=2020, last_year=2100, axis=1),
+    meta=co2.apply(pyam.timeseries.cumulative, first_year=2020, last_year=2100, axis=1),
     name="cumulative_co2",
 )
 

diff --git a/docs/tutorials/aggregating_downscaling_consistency.ipynb b/docs/tutorials/aggregating_downscaling_consistency.ipynb
@@ -55,7 +55,7 @@
    "outputs": [],
    "source": [
     "import pandas as pd\n",
-    "import pyam"
+    "from pyam import IamDataFrame"
    ]
   },
   {
@@ -73,7 +73,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "df = pyam.IamDataFrame(data='tutorial_data_aggregating_downscaling.csv')"
+    "df = IamDataFrame(data='tutorial_data_aggregating_downscaling.csv')"
    ]
   },
   {
@@ -421,7 +421,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "tutorial_df = pyam.IamDataFrame(pd.DataFrame([\n",
+    "tutorial_df = IamDataFrame(pd.DataFrame([\n",
     "    ['World', 'Primary Energy', 'EJ/yr', 7, 15],\n",
     "    ['World', 'Primary Energy|Coal', 'EJ/yr', 4, 11],\n",
     "    ['World', 'Primary Energy|Wind', 'EJ/yr', 2, 4],\n",
@@ -483,7 +483,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -497,7 +497,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.3"
+   "version": "3.10.0"
   }
  },
  "nbformat": 4,

diff --git a/docs/tutorials/aggregating_variables_and_plotting_with_negative_values.ipynb b/docs/tutorials/aggregating_variables_and_plotting_with_negative_values.ipynb
@@ -18,7 +18,7 @@
     "import numpy as np\n",
     "import pandas as pd\n",
     "\n",
-    "import pyam"
+    "from pyam import IamDataFrame"
    ]
   },
   {
@@ -46,7 +46,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "df = pyam.IamDataFrame(pd.DataFrame([\n",
+    "df = IamDataFrame(pd.DataFrame([\n",
     "    ['IMG', 'a_scen', 'World', 'Emissions|CO2|Energy|Oil', 'Mt CO2/yr', 2, 3.2, 2.0, 1.8],\n",
     "    ['IMG', 'a_scen', 'World', 'Emissions|CO2|Energy|Gas', 'Mt CO2/yr', 1.3, 1.6, 1.0, 0.7],\n",
     "    ['IMG', 'a_scen', 'World', 'Emissions|CO2|Energy|BECCS', 'Mt CO2/yr', 0.0, 0.4, -0.4, 0.3],\n",
@@ -164,7 +164,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "df = pyam.IamDataFrame(pd.DataFrame([\n",
+    "df = IamDataFrame(pd.DataFrame([\n",
     "    ['IMG', 'a_scen', 'World', 'Emissions|CO2', 'Mt CO2/yr', 4.6, 5.3, 5.5, 4.3],\n",
     "    ['IMG', 'a_scen', 'World', 'Emissions|CO2|Fossil', 'Mt CO2/yr', 4.0, 4.6, 4.9, 4.1],\n",
     "    ['IMG', 'a_scen', 'World', 'Emissions|CO2|AFOLU', 'Mt CO2/yr', 0.6, 0.7, 0.6, 0.2],\n",
@@ -235,7 +235,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Even if there are sectors which are defined only at the world level (e.g. `Emissions|CO2|Fossil|Aviation` in our example), Pyam will find them and include them when calculating the regional total if we specify `components=True` when using `aggregate_region`."
+    "Even if there are sectors which are defined only at the world level (e.g. `Emissions|CO2|Fossil|Aviation` in our example), **pyam** will find them and include them when calculating the regional total if we specify `components=True` when using `aggregate_region`."
    ]
   },
   {
@@ -300,7 +300,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -314,7 +314,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.6"
+   "version": "3.10.0"
   }
  },
  "nbformat": 4,

diff --git a/docs/tutorials/algebraic_operations.ipynb b/docs/tutorials/algebraic_operations.ipynb
@@ -50,7 +50,7 @@
    "outputs": [],
    "source": [
     "import pandas as pd\n",
-    "import pyam"
+    "from pyam import IamDataFrame"
    ]
   },
   {
@@ -68,7 +68,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "df = pyam.IamDataFrame(data='tutorial_data_aggregating_downscaling.csv')\n",
+    "df = IamDataFrame(data='tutorial_data_aggregating_downscaling.csv')\n",
     "df"
    ]
   },
@@ -334,7 +334,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -348,7 +348,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.3"
+   "version": "3.10.0"
   }
  },
  "nbformat": 4,

diff --git a/docs/tutorials/data_table_formats.ipynb b/docs/tutorials/data_table_formats.ipynb
@@ -47,7 +47,7 @@
    "outputs": [],
    "source": [
     "import pandas as pd\n",
-    "import pyam"
+    "from pyam import IamDataFrame, IAMC_IDX"
    ]
   },
   {
@@ -74,7 +74,7 @@
     "    ['model_a', 'scen_a', 'World', 'Primary Energy|Coal', 'EJ/y', 0.5, 3],\n",
     "    ['model_a', 'scen_b', 'World', 'Primary Energy', 'EJ/y', 2, 7],\n",
     "],\n",
-    "    columns=pyam.IAMC_IDX + [2005, 2010],\n",
+    "    columns=IAMC_IDX + [2005, 2010],\n",
     ")\n",
     "\n",
     "SIMPLE_DF"
@@ -86,7 +86,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "df_simple = pyam.IamDataFrame(SIMPLE_DF)"
+    "df_simple = IamDataFrame(SIMPLE_DF)"
    ]
   },
   {
@@ -132,7 +132,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "df_missing_cols = pyam.IamDataFrame(MISSING_COLS_DF, model='model_a')"
+    "df_missing_cols = IamDataFrame(MISSING_COLS_DF, model='model_a')"
    ]
   },
   {
@@ -169,7 +169,7 @@
     "    ['model_a', 'scen_b', 'World', 'Primary Energy', 'EJ/y', 2005, 2],\n",
     "    ['model_a', 'scen_b', 'World', 'Primary Energy', 'EJ/y', 2010, 7],\n",
     "],\n",
-    "    columns=pyam.IAMC_IDX + ['year', 'value'],\n",
+    "    columns=IAMC_IDX + ['year', 'value'],\n",
     ")\n",
     "\n",
     "LONG_DF"
@@ -181,7 +181,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "df_long = pyam.IamDataFrame(LONG_DF)"
+    "df_long = IamDataFrame(LONG_DF)"
    ]
   },
   {
@@ -217,8 +217,7 @@
     "    ['model_a', 'scen_b', 'World', 'EJ/y', 2005, 2, None],\n",
     "    ['model_a', 'scen_b', 'World', 'EJ/y', 2010, 7, None]\n",
     "],\n",
-    "    columns=['model', 'scenario', 'region', 'unit', 'year',\n",
-    "             'Primary Energy', 'Primary Energy|Coal'],\n",
+    "    columns=['model', 'scenario', 'region', 'unit', 'year', 'Primary Energy', 'Primary Energy|Coal'],\n",
     ")\n",
     "\n",
     "VALUE_COLS_DF"
@@ -230,8 +229,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "df_value_cols = pyam.IamDataFrame(VALUE_COLS_DF,\n",
-    "                                  value=['Primary Energy', 'Primary Energy|Coal'])"
+    "df_value_cols = IamDataFrame(\n",
+    "    VALUE_COLS_DF,\n",
+    "    value=['Primary Energy', 'Primary Energy|Coal']\n",
+    ")"
    ]
   },
   {
@@ -277,7 +278,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "df_other_header = pyam.IamDataFrame(OTHER_HEADER_DF, scenario='foo')"
+    "df_other_header = IamDataFrame(OTHER_HEADER_DF, scenario='foo')"
    ]
   },
   {
@@ -324,7 +325,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "df_concat = pyam.IamDataFrame(CONCAT_DF, variable=['var_1', 'var_2'])"
+    "df_concat = IamDataFrame(CONCAT_DF, variable=['var_1', 'var_2'])"
    ]
   },
   {
@@ -379,9 +380,14 @@
    "outputs": [],
    "source": [
     "df_complicated = (\n",
-    "    pyam.IamDataFrame(COMPLICATED_DF, model='model_a', region='iso',\n",
-    "                      value=['primary', 'coal'])\n",
-    "    .rename(variable={'primary': 'Primary Energy', 'coal': 'Primary Energy|Coal'})\n",
+    "    IamDataFrame(\n",
+    "        COMPLICATED_DF,\n",
+    "        model='model_a',\n",
+    "        region='iso',\n",
+    "        value=['primary', 'coal']\n",
+    "    ).rename(\n",
+    "        variable={'primary': 'Primary Energy', 'coal': 'Primary Energy|Coal'}\n",
+    "    )\n",
     ")"
    ]
   },
@@ -423,7 +429,7 @@
     "    ['model_a', 'scen_a', 'World', 'Primary Energy|Coal', 'EJ/y', 2.1, 0.5, 3],\n",
     "    ['model_a', 'scen_b', 'World', 'Primary Energy', 'EJ/y', 2.1, 2, 7],\n",
     "],\n",
-    "    columns=pyam.IAMC_IDX + ['version', 2005, 2010],\n",
+    "    columns=IAMC_IDX + ['version', 2005, 2010],\n",
     ")\n",
     "\n",
     "CUSTOM_COL_DF"
@@ -435,7 +441,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "df_custom_col = pyam.IamDataFrame(CUSTOM_COL_DF)"
+    "df_custom_col = IamDataFrame(CUSTOM_COL_DF)"
    ]
   },
   {
@@ -450,7 +456,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -464,7 +470,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.3"
+   "version": "3.10.0"
   }
  },
  "nbformat": 4,

diff --git a/docs/tutorials/iiasa_dbs.ipynb b/docs/tutorials/iiasa_dbs.ipynb
@@ -300,7 +300,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -314,7 +314,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.7"
+   "version": "3.10.0"
   }
  },
  "nbformat": 4,