From 145a03e1b8e81965d3418057f1b07a51f83c20d0 Mon Sep 17 00:00:00 2001 From: Tom Vo Date: Tue, 16 Apr 2024 09:41:32 -0700 Subject: [PATCH] Add instructions for setting `ESMFMKFILE` and update links to xESMF docs (#643) --- README.rst | 2 +- docs/examples/regridding-horizontal.ipynb | 29 ++++++++++++++------- docs/getting-started-guide/installation.rst | 22 +++++++++++++++- docs/getting-started-guide/overview.rst | 2 +- xcdat/regridder/accessor.py | 2 +- 5 files changed, 44 insertions(+), 13 deletions(-) diff --git a/README.rst b/README.rst index 58633a23..4a6fe9ad 100644 --- a/README.rst +++ b/README.rst @@ -182,7 +182,7 @@ Things We Are Striving For * Support for parallelism using `dask`_ where it is both possible and makes sense .. _Metadata Interpretation: https://xcdat.readthedocs.io/en/stable/faqs.html#metadata-interpretation -.. _xESMF: https://pangeo-xesmf.readthedocs.io/en/latest/ +.. _xESMF: https://xesmf.readthedocs.io/en/latest/ .. _regrid2: https://cdms.readthedocs.io/en/latest/regrid2.html .. _xgcm: https://xgcm.readthedocs.io/en/latest/index.html .. _dask: https://dask.org/ diff --git a/docs/examples/regridding-horizontal.ipynb b/docs/examples/regridding-horizontal.ipynb index 47af7b0c..13835fe4 100644 --- a/docs/examples/regridding-horizontal.ipynb +++ b/docs/examples/regridding-horizontal.ipynb @@ -17,7 +17,10 @@ "\n", "- [xarray.Dataset.regridder.horizontal](../generated/xarray.Dataset.regridder.horizontal.rst)\n", "\n", - "The data used in this example can be found through the [Earth System Grid Federation (ESGF) search portal](https://aims2.llnl.gov/search).\n", + "## Other Resources\n", + "\n", + "- [xESMF documentation](https://xesmf.readthedocs.io/en/latest/)\n", + "- The data used in this example can be found through the [Earth System Grid Federation (ESGF) search portal](https://aims2.llnl.gov/search).\n", "\n", "## Overview\n", "\n", @@ -653,7 +656,7 @@ "# Unit adjust (-273.15, K to C)\n", "ds[\"tas\"] = ds[\"tas\"] - 273.15\n", "\n", - "ds\n" + "ds" ] }, { @@ -751,10 +754,12 @@ "\n", "fig, axes = plt.subplots(ncols=2, figsize=(16, 4))\n", "\n", - "ds.tas.isel(time=0).plot(ax=axes[0], vmin=-40, vmax=40, extend='both', cmap = 'RdBu_r')\n", + "ds.tas.isel(time=0).plot(ax=axes[0], vmin=-40, vmax=40, extend=\"both\", cmap=\"RdBu_r\")\n", "axes[0].set_title(\"Input data\")\n", "\n", - "output.tas.isel(time=0).plot(ax=axes[1], vmin=-40, vmax=40, extend='both', cmap = 'RdBu_r')\n", + "output.tas.isel(time=0).plot(\n", + " ax=axes[1], vmin=-40, vmax=40, extend=\"both\", cmap=\"RdBu_r\"\n", + ")\n", "axes[1].set_title(\"Output data\")\n", "\n", "plt.tight_layout()" @@ -771,7 +776,7 @@ "\n", "In this example, we will compare the different regridding methods supported by `xESMF`.\n", "\n", - "You can find a more in depth comparison on `xESMF`'s [documentation](https://pangeo-xesmf.readthedocs.io/en/latest/notebooks/Compare_algorithms.html).\n", + "You can find a more in depth comparison on `xESMF`'s [documentation](https://xesmf.readthedocs.io/en/latest/notebooks/Compare_algorithms.html).\n", "\n", "Methods:\n", "\n", @@ -809,7 +814,9 @@ "for i, method in enumerate(methods):\n", " output = ds.regridder.horizontal(\"tas\", output_grid, tool=\"xesmf\", method=method)\n", "\n", - " output.tas.isel(time=0).plot(ax=axes[i], vmin=-40, vmax=40, extend='both', cmap = 'RdBu_r')\n", + " output.tas.isel(time=0).plot(\n", + " ax=axes[i], vmin=-40, vmax=40, extend=\"both\", cmap=\"RdBu_r\"\n", + " )\n", "\n", " axes[i].set_title(method)\n", "\n", @@ -861,7 +868,9 @@ "ds[\"mask\"].plot(ax=axes[0], cmap=\"binary_r\")\n", "axes[0].set_title(\"Mask\")\n", "\n", - "masked_output.tas.isel(time=0).plot(ax=axes[1], vmin=-40, vmax=40, extend='both', cmap='RdBu_r')\n", + "masked_output.tas.isel(time=0).plot(\n", + " ax=axes[1], vmin=-40, vmax=40, extend=\"both\", cmap=\"RdBu_r\"\n", + ")\n", "axes[1].set_title(\"Masked output\")\n", "\n", "plt.tight_layout()" @@ -915,9 +924,11 @@ "\n", "fig, axes = plt.subplots(ncols=2, figsize=(16, 4))\n", "\n", - "ds.tas.isel(time=0).plot(ax=axes[0], vmin=-40, vmax=40, extend='both', cmap = 'RdBu_r')\n", + "ds.tas.isel(time=0).plot(ax=axes[0], vmin=-40, vmax=40, extend=\"both\", cmap=\"RdBu_r\")\n", "\n", - "output.tas.isel(time=0).plot(ax=axes[1], vmin=-40, vmax=40, extend='both', cmap = 'RdBu_r')" + "output.tas.isel(time=0).plot(\n", + " ax=axes[1], vmin=-40, vmax=40, extend=\"both\", cmap=\"RdBu_r\"\n", + ")" ] } ], diff --git a/docs/getting-started-guide/installation.rst b/docs/getting-started-guide/installation.rst index 73f65858..a78df825 100644 --- a/docs/getting-started-guide/installation.rst +++ b/docs/getting-started-guide/installation.rst @@ -77,7 +77,6 @@ Instructions .. _mamba create: https://mamba.readthedocs.io/en/latest/user_guide/mamba.html#quickstart .. _mamba install: https://mamba.readthedocs.io/en/latest/user_guide/mamba.html#quickstart - Updating -------- @@ -95,3 +94,24 @@ To update to a specific version of ``xcdat``: >>> mamba activate >>> mamba update xcdat= + +Jupyter Users set ``ESMFMKFILE`` env variable +--------------------------------------------- + +If you are a Jupyter user, the ``ESMFMKFILE`` environment variable will need to be set +either directly on the machine or through your Jupyter Notebook. + +This env variable is normally set when calling ``conda activate`` with the conda +environment that has ``xesmf``. However, Jupyter does not run ``conda activate`` when using +the Python kernel associated with the environment so ``ESMFMKFILE`` is not set, resulting +in ``ImportError: The ESMFMKFILE environment variable is not available.`` (related `GitHub +Issue `_). + +To set the ``ESMFMKFILE`` in a Jupyter Notebook add: + +.. code-block:: python + + >>> import os + >>> os.environ['ESMFMKFILE'] = 'conda-envs/xcdat/lib/esmf.mk' + >>> + >>> import xcdat diff --git a/docs/getting-started-guide/overview.rst b/docs/getting-started-guide/overview.rst index 70bc8e38..4e610bec 100644 --- a/docs/getting-started-guide/overview.rst +++ b/docs/getting-started-guide/overview.rst @@ -132,7 +132,7 @@ Things We Are Striving For * Support for parallelism using `dask`_ where it is both possible and makes sense .. _Metadata Interpretation: https://xcdat.readthedocs.io/en/stable/faqs.html#metadata-interpretation -.. _xESMF: https://pangeo-xesmf.readthedocs.io/en/latest/ +.. _xESMF: https://xesmf.readthedocs.io/en/latest/ .. _regrid2: https://cdms.readthedocs.io/en/latest/regrid2.html .. _xgcm: https://xgcm.readthedocs.io/en/latest/index.html .. _dask: https://dask.org/ diff --git a/xcdat/regridder/accessor.py b/xcdat/regridder/accessor.py index b4b34d95..0001c954 100644 --- a/xcdat/regridder/accessor.py +++ b/xcdat/regridder/accessor.py @@ -135,7 +135,7 @@ def horizontal( Supported tools, methods and grids: - - xESMF (https://pangeo-xesmf.readthedocs.io/en/latest/) + - xESMF (https://xesmf.readthedocs.io/en/latest/) - Methods: Bilinear, Conservative, Conservative Normed, Patch, Nearest s2d, or Nearest d2s. - Grids: Rectilinear, or Curvilinear. - Find options at :py:func:`xcdat.regridder.xesmf.XESMFRegridder`