Skip to content

Commit

Permalink
Some cleanup and docs (#1457)
Browse files Browse the repository at this point in the history
fmaussion authored Sep 5, 2022
1 parent d8da869 commit 448d817
Showing 9 changed files with 95 additions and 137 deletions.
2 changes: 1 addition & 1 deletion docs/conf.py
Original file line number Diff line number Diff line change
@@ -166,7 +166,7 @@
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
language = 'en'

# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
161 changes: 37 additions & 124 deletions docs/installing-oggm.rst
Original file line number Diff line number Diff line change
@@ -94,82 +94,43 @@ This is the recommended way to install OGGM for most users.
Prerequisites
~~~~~~~~~~~~~

You should have a recent version of the `conda`_ package manager.
You can get `conda`_ by installing `miniconda`_ (the package manager alone -
recommended) or `anaconda`_ (the full suite - with many packages you won't
need).


.. _miniconda: http://conda.pydata.org/miniconda.html
.. _anaconda: http://docs.continuum.io/anaconda/install

Conda environment
~~~~~~~~~~~~~~~~~

We recommend to create a specific `environment`_ for OGGM. In a terminal
window, type::

conda create --name oggm_env python=3.X


where ``3.X`` is the Python version shipped with conda (currently 3.9).
You can of course use any other name for your environment.

Don't forget to activate it before going on::

source activate oggm_env


.. _environment: https://conda.io/projects/conda/en/latest/user-guide/concepts/environments.html


In a hurry? Try mamba (optional)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The conda package manager has been criticized for being slow (it *is*
quite slow to be honest). A new, faster tool is now available
to replace conda: `mamba <https://mamba.readthedocs.io>`_. Mamba is a drop-in
You should have a recent version of the `conda`_ package manager. Our
recommendation is to install `mambaforge`_. If you are completely
new to these things, check out
`this page <https://fabienmaussion.info/intro_to_programming/week_01/01-Installation.html>`_
which explains how to install ``mambaforge`` and
`this one <https://fabienmaussion.info/intro_to_programming/week_05/01-install-packages.html>`_
for installing packages.

We recommend to use `mamba <https://mamba.readthedocs.io>`_ over conda as an
installation command. Mamba is a drop-in
replacement for all conda commands. If you feel like it, install mamba in your conda
environment (``conda install -c conda-forge mamba``)
and replace all occurrences of ``conda`` with ``mamba`` in the instructions below.

*Note March 2022*: soon, conda will use mamba per default. See
*Note 2022*: soon, conda will use mamba per default. See
`this post <https://www.anaconda.com/blog/a-faster-conda-for-a-growing-community>`_
for more info.

.. _miniconda: http://conda.pydata.org/miniconda.html
.. _mambaforge: https://github.com/conda-forge/miniforge#mambaforge

Install dependencies
~~~~~~~~~~~~~~~~~~~~

Install all OGGM dependencies from the ``conda-forge`` and ``oggm`` conda channels::

mamba install -c oggm -c conda-forge oggm-deps

The ``oggm-deps`` package is a "meta package". It does not contain any code but
will install all the packages OGGM needs automatically.

.. important::

The `conda-forge`_ channel ensures that the complex package dependencies are
handled correctly. Subsequent installations or upgrades from the default
conda channel might brake the chain. We strongly
recommend to **always** use the the `conda-forge`_ channel for your
installation.

You might consider setting `conda-forge`_ as your
default channel::

conda config --add channels conda-forge
The simplest way: with an environment file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

No scientific Python installation is complete without installing a good
testing framework, as well as `IPython`_ and `Jupyter`_::
Download (right-click -> "save as") or copy the content of
`this file <https://raw.githubusercontent.com/OGGM/oggm/master/docs/recommended_env.yml>`_
into a file called ``environment.yml`` on your system.

mamba install -c conda-forge pytest ipython jupyter
From the location of the file, run ``mamba env create -f environment.yml``.

.. _conda-forge: https://conda-forge.github.io/
.. _IPython: https://ipython.org/
.. _Jupyter: https://jupyter.org/
This will create a new environment called ``oggm_env`` in your conda installation.
For more information about conda environments, visit the
`conda documentation on the topic <https://conda.io/projects/conda/en/latest/user-guide/concepts/environments.html>`_. Similarly,
visit `conda documentation on environment files <https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-from-an-environment-yml-file>`_
for more information about how to create an environment from a ``yml`` file.

Don't forget to :ref:`test-oggm` before using it!

Install OGGM itself
~~~~~~~~~~~~~~~~~~~
@@ -188,11 +149,12 @@ First, choose which version of OGGM you would like to install:

**‣ install the stable version:**

If you are using conda, you can install stable OGGM as a normal conda package::
.. note::

mamba install -c oggm oggm
If you installed OGGM with the environment file above, OGGM will be installed
already in the latest **stable** version.

If you are using pip, you can install OGGM from `PyPI <https://pypi.python.org/pypi/oggm>`_::
In your conda environment, use pip::

pip install oggm

@@ -206,7 +168,6 @@ system. In your conda environment, simply do::
With this command you can also update an already installed OGGM version
to the latest version.


**‣ install the dev version + get access to the OGGM code:**

For this to work you'll need to have the `git`_ software installed on your
@@ -235,9 +196,12 @@ And install OGGM in development mode (this is valid for both **pip** and

.. _git pull: https://git-scm.com/docs/git-pull

Don't forget to :ref:`test-oggm` before using it!

Testing OGGM
~~~~~~~~~~~~
.. _test-oggm:

Test OGGM
~~~~~~~~~

You can test your OGGM installation by running the following command from
anywhere (don't forget to activate your environment first)::
@@ -303,59 +267,8 @@ If the tests don't pass, a diagnostic of which package creates the errors
might be necessary. Errors like ``segmentation fault`` or ``Proj Error``
are frequent and point to errors in upstream packages, rarely in OGGM itself.

If you are having troubles, installing the packages manually from a fresh
environment might help. At the time of writing (20.01.2021), creating an
environment from the following ``environment.yml`` file used to work::

name: oggm_env
channels:
- conda-forge
dependencies:
- jupyter
- jupyterlab
- numpy
- scipy
- pandas
- shapely
- matplotlib
- Pillow
- netcdf4
- scikit-image
- scikit-learn
- configobj
- xarray
- pytest
- dask
- bottleneck
- pyproj
- cartopy
- geopandas
- rasterio<1.2.10
- rioxarray
- seaborn
- pytables
- salem
- motionless
- sphinx
- sphinx-book-theme
- ipython
- numpydoc
- seaborn
- sphinx-intl
- pip:
- joblib
- progressbar2
- sphinx-togglebutton
- git+https://github.com/OGGM/pytest-mpl
- oggm


See the
`conda docs <https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-from-an-environment-yml-file>`_
for more information about how to create an environment from a ``yml`` file, OR
you can do what I usually do (much faster): install `mamba`_
first, then run ``mamba env create -f environment.yml``.

If you encounter issues, please get in touch with
us `on github <https://github.com/OGGM/oggm/issues>`_.

.. _virtualenv-install:

@@ -366,7 +279,7 @@ Install with pyenv (Linux)

We recommend our users to use ``conda`` instead of ``pip``, because
of the ease of installation with ``conda``. If you are familiar with ``pip`` and
``pyenv``, the instructions below work as well: as of Sept 2020 (and thanks
``pyenv``, the instructions below work as well: as of Sept 2022 (and thanks
to pip wheels), a pyenv
installation is possible without major issue on Debian/Ubuntu/Mint
systems.
42 changes: 42 additions & 0 deletions docs/recommended_env.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
name: oggm_env
channels:
- conda-forge
dependencies:
- jupyter
- jupyterlab
- numpy
- scipy
- pandas
- shapely
- matplotlib
- Pillow
- netcdf4
- scikit-image
- scikit-learn
- configobj
- xarray
- pytest
- dask
- bottleneck
- pyproj
- cartopy
- geopandas
- rasterio
- rioxarray
- seaborn
- pytables
- salem
- motionless
- sphinx
- sphinx-book-theme>=0.3.3
- ipython
- numpydoc
- seaborn
- sphinx-intl
- pip
- pip:
- joblib
- progressbar2
- sphinx-togglebutton
- git+https://github.com/OGGM/pytest-mpl
- oggm
2 changes: 1 addition & 1 deletion oggm/core/flowline.py
Original file line number Diff line number Diff line change
@@ -1170,7 +1170,7 @@ def run_until_and_store(self, y1,
diag_ds['is_fixed_geometry_spinup'].attrs['description'] = desc
diag_ds['is_fixed_geometry_spinup'].attrs['unit'] = '-'
elif make_compatible:
is_spinup_time = np.full(len(monthly_time), False, dtype=np.bool)
is_spinup_time = np.full(len(monthly_time), False, dtype=bool)
diag_ds['is_fixed_geometry_spinup'] = ('time', is_spinup_time)
desc = 'Part of the series which are spinup'
diag_ds['is_fixed_geometry_spinup'].attrs['description'] = desc
8 changes: 4 additions & 4 deletions oggm/shop/gcm_climate.py
Original file line number Diff line number Diff line change
@@ -262,8 +262,8 @@ def process_monthly_isimip_data(gdir, output_filesuffix='',
c = ((tempds_gcm.longitude - glon) ** 2 +
(tempds_gcm.latitude - glat) ** 2)
# first select gridpoint, then merge, should be faster!!!
temp_a_gcm = tempds_gcm.isel(points=c.argmin())
temp_a_hist = tempds_hist.isel(points=c.argmin())
temp_a_gcm = tempds_gcm.isel(points=np.argmin(c.data))
temp_a_hist = tempds_hist.isel(points=np.argmin(c.data))
# merge historical with gcm together
# TODO: change to drop_conflicts when xarray version v0.17.0 can
# be used with salem
@@ -280,8 +280,8 @@ def process_monthly_isimip_data(gdir, output_filesuffix='',

c = ((precipds_gcm.longitude - glon) ** 2 +
(precipds_gcm.latitude - glat) ** 2)
precip_a_gcm = precipds_gcm.isel(points=c.argmin())
precip_a_hist = precipds_hist.isel(points=c.argmin())
precip_a_gcm = precipds_gcm.isel(points=np.argmin(c.data))
precip_a_hist = precipds_hist.isel(points=np.argmin(c.data))
precip_a = xr.merge([precip_a_gcm, precip_a_hist],
combine_attrs='override')

8 changes: 4 additions & 4 deletions oggm/shop/w5e5.py
Original file line number Diff line number Diff line change
@@ -120,7 +120,7 @@ def process_gswp3_w5e5_data(gdir, y0=None, y1=None, output_filesuffix=None):
try:
# computing all the distances and choose the nearest gridpoint
c = (ds.longitude - lon)**2 + (ds.latitude - lat)**2
ds = ds.isel(points=c.argmin())
ds = ds.isel(points=np.argmin(c.data))
except ValueError:
ds = ds.sel(longitude=lon, latitude=lat, method='nearest')
# normally if I do the flattening, this here should not occur
@@ -149,7 +149,7 @@ def process_gswp3_w5e5_data(gdir, y0=None, y1=None, output_filesuffix=None):
try:
# ... prcp is also flattened
c = (ds.longitude - lon)**2 + (ds.latitude - lat)**2
ds = ds.isel(points=c.argmin())
ds = ds.isel(points=np.argmin(c.data))
except ValueError:
# this should not occur
ds = ds.sel(longitude=lon, latitude=lat, method='nearest')
@@ -164,7 +164,7 @@ def process_gswp3_w5e5_data(gdir, y0=None, y1=None, output_filesuffix=None):
try:
# Flattened (only possibility at the moment)
c = (ds.longitude - lon)**2 + (ds.latitude - lat)**2
ds = ds.isel(points=c.argmin())
ds = ds.isel(points=np.argmin(c.data))
except ValueError:
# this should not occur
ds = ds.sel(longitude=lon, latitude=lat, method='nearest')
@@ -218,7 +218,7 @@ def process_gswp3_w5e5_data(gdir, y0=None, y1=None, output_filesuffix=None):
try:
# ... prcp is also flattened
c = (ds.longitude - lon)**2 + (ds.latitude - lat)**2
ds = ds.isel(points=c.argmin())
ds = ds.isel(points=np.argmin(c.data))
except ValueError:
# this should not occur
ds = ds.sel(longitude=lon, latitude=lat, method='nearest')
6 changes: 4 additions & 2 deletions oggm/tests/test_prepro.py
Original file line number Diff line number Diff line change
@@ -2094,12 +2094,14 @@ def test_ref_mb_glaciers(self):

def test_fake_ref_mb_glacier(self):

testdir = os.path.join(self.testdir, 'fake_ref')

hef_file = get_demo_file('Hintereisferner_RGI5.shp')
entity = gpd.read_file(hef_file).iloc[0]
gdir1 = oggm.GlacierDirectory(entity, base_dir=self.testdir)
gdir1 = oggm.GlacierDirectory(entity, base_dir=testdir)
climate.process_custom_climate_data(gdir1)
entity['RGIId'] = 'RGI50-11.99999'
gdir2 = oggm.GlacierDirectory(entity, base_dir=self.testdir)
gdir2 = oggm.GlacierDirectory(entity, base_dir=testdir)
climate.process_custom_climate_data(gdir2)

ref_gd = utils.get_ref_mb_glaciers([gdir2])
1 change: 1 addition & 0 deletions oggm/tests/test_workflow.py
Original file line number Diff line number Diff line change
@@ -337,6 +337,7 @@ def test_random(self):
workflow.execute_entity_task(flowline.run_random_climate, gdirs,
nyears=100, seed=0,
store_monthly_step=True,
mb_elev_feedback='monthly',
output_filesuffix='_test')

for gd in gdirs:
2 changes: 1 addition & 1 deletion oggm/utils/_downloads.py
Original file line number Diff line number Diff line change
@@ -69,7 +69,7 @@
# The given commit will be downloaded from github and used as source for
# all sample data
SAMPLE_DATA_GH_REPO = 'OGGM/oggm-sample-data'
SAMPLE_DATA_COMMIT = 'c0c2ad2a7718ccedb23380c3df05acb3fc726840'
SAMPLE_DATA_COMMIT = 'f94ba47fc7c3d0355b806e622e330106e08cc16f'

GDIR_L1L2_URL = ('https://cluster.klima.uni-bremen.de/~oggm/gdirs/oggm_v1.4/'
'L1-L2_files/centerlines/')

0 comments on commit 448d817

Please sign in to comment.