Getting started

The ultimate goal of OGGM will be to hide the python workflow behind the model entirely, and run it only using configuration files and scripts. We are not there yet, and if you want to use and participate to the development of OGGM you’ll have to get your hands dirty. We hope however that the workflow is structured enough so that it is possible to jump in without having to understand all of its internals.

The few examples below are meant to illustrate the general design of OGGM, without going into the details of the implementation.

Imports

The following imports are necessary for all of the examples:

In [1]: import geopandas as gpd

In [2]: import oggm

In [3]: from oggm import cfg, tasks, graphics

In [4]: from oggm.utils import get_demo_file

Initialisation and GlacierDirectories

The first thing to do when running OGGM is to initialise it. This function will read the default configuration file which contains all user defined parameters:

In [5]: cfg.initialize()

These parameters are now accessible to all OGGM routines. For example, the cfg.PARAMS dict contains some runtime parameters, while cfg.PATHS stores the paths to the input files and the working directory (where the model output will be written):

In [6]: cfg.PARAMS['topo_interp']
Out[6]: 'cubic'

In [7]: cfg.PARAMS['temp_default_gradient']
Out[7]: -0.0065

In [8]: cfg.PATHS
Out[8]: 
PathOrderedDict([('dl_cache_dir', '/home/docs/OGGM/download_cache'),
                 ('tmp_dir', '/home/docs/OGGM/tmp'),
                 ('cru_dir', '/home/docs/OGGM/cru'),
                 ('rgi_dir', '/home/docs/OGGM/rgi'),
                 ('test_dir', '/home/docs/OGGM/tests'),
                 ('working_dir', ''),
                 ('dem_file', ''),
                 ('climate_file', '')])

We’ll use some demo files (shipped with OGGM) for the basic input:

In [9]: cfg.PATHS['dem_file'] = get_demo_file('hef_srtm.tif') # topography

The starting point of a run is always a valid RGI file. In this case we use a very small subset of the RGI, the outlines of the Hinereisferner (HEF) in the Austrian Alps:

In [10]: entity = gpd.GeoDataFrame.from_file(get_demo_file('HEF_MajDivide.shp')).iloc[0]

In [11]: entity
Out[11]: 
Area                                                  6.24736
Aspect                                                     71
BgnDate                                              20030799
CenLat                                                46.8003
CenLon                                                10.7584
EndDate                                              20030999
GLIMSId                                        G010758E46800N
GlacType                                                 0091
Lmax                                                     7178
Name                                          Hintereisferner
O1Region                                                   11
O2Region                                                    1
RGIFlag                                                  0909
RGIId                                          RGI50-11.00897
Slope                                                      16
Zmax                                                     3674
Zmed                                                     3050
Zmin                                                     2430
geometry    POLYGON ((10.74505084001018 46.80376064580748,...
Name: 0, dtype: object

This information is enough to define HEF’s GlacierDirectory:

In [12]: gdir = oggm.GlacierDirectory(entity)
---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
<ipython-input-12-59a76489ffa1> in <module>()
----> 1 gdir = oggm.GlacierDirectory(entity)

/home/docs/checkouts/readthedocs.org/user_builds/oggm/conda/latest/lib/python3.5/site-packages/oggm-0.1.1+301.gcca3c42-py3.5.egg/oggm/utils.py in __init__(self, rgi_entity, base_dir, reset)
   2477         if base_dir is None:
   2478             if not cfg.PATHS.get('working_dir', None):
-> 2479                 raise ValueError("Need a valid PATHS['working_dir']!")
   2480             base_dir = os.path.join(cfg.PATHS['working_dir'], 'per_glacier')
   2481 

ValueError: Need a valid PATHS['working_dir']!

Glacier working directories have two major purposes:

  • carry information about the glacier attributes
  • handle I/O and filepaths operations

For example, it will tell OGGM where to write the data for this glacier or its terminus type:

In [13]: gdir.dir
Out[13]: '/home/docs/OGGM_docs/Flowlines/RGI50-11/RGI50-11.00/RGI50-11.00897'

In [14]: gdir.terminus_type
Out[14]: 'Land-terminating'

GlacierDirectories are the input to most OGGM functions. In fact, they are the only required input to all Entity tasks. These entity tasks are processes which can run on one glacier at a time (the vast majority of OGGM tasks are entity tasks). The first task to apply to an empty GlacierDirectory is tasks.define_glacier_region(), which sets the local glacier map and topography, and tasks.glacier_masks(), which prepares gridded topography data:

In [15]: tasks.define_glacier_region(gdir, entity=entity)

In [16]: tasks.glacier_masks(gdir)

In [17]: os.listdir(gdir.dir)
Out[17]: 
['intersects.cpg',
 'outlines.dbf',
 'downstream_line.pkl',
 'geometries.pkl',
 'inversion_flowlines.pkl',
 'outlines.cpg',
 'intersects.shx',
 'dem_source.pkl',
 'centerlines.pkl',
 'intersects.shp',
 'gridded_data.nc',
 'outlines.shx',
 'catchment_indices.pkl',
 'intersects.prj',
 'outlines.shp',
 'log.txt',
 'dem.tif',
 'glacier_grid.json',
 'intersects.dbf',
 'outlines.prj']

The directory is now filled with data. Other tasks can build upon these, for example the plotting functions:

In [18]: graphics.plot_domain(gdir)
_images/plot_domain.png

What next?

This documentation is growing step by step. In the meantime, a good place to start is the oggm/docs/notebooks directory.

You will find two notebooks:

  • getting_started.ipynb, which set-ups an entire OGGM run in the Ötztal region.
  • flowline_model.ipynb, which describes the usage of the flowline model for idealized test cases.