Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
281 lines (206 sloc) 6.8 KB

API Reference

.. currentmodule:: oggm

This page lists all available functions and classes in OGGM. It is a hard work to keep everything up-to-date, so don't hesitate to let us know (see :ref:`contact`) if something's missing, or help us (see :ref:`contributing`) to write a better documentation!

Workflow

Tools to set-up and run OGGM.

.. autosummary::
    :toctree: generated/
    :nosignatures:

    cfg.initialize
    cfg.set_logging_config
    cfg.set_intersects_db
    cfg.reset_working_dir
    workflow.init_glacier_regions
    workflow.execute_entity_task
    workflow.gis_prepro_tasks
    workflow.climate_tasks
    workflow.inversion_tasks
    workflow.merge_glacier_tasks
    utils.compile_glacier_statistics
    utils.compile_run_output
    utils.compile_climate_input
    utils.compile_task_log
    utils.copy_to_basedir
    utils.gdir_to_tar
    utils.base_dir_to_tar


Troubleshooting

.. autosummary::
    :toctree: generated/
    :nosignatures:

    utils.show_versions


Input/Output

.. autosummary::
    :toctree: generated/
    :nosignatures:

    utils.get_demo_file
    utils.get_rgi_dir
    utils.get_rgi_region_file
    utils.get_rgi_glacier_entities
    utils.get_rgi_intersects_dir
    utils.get_rgi_intersects_region_file
    utils.get_rgi_intersects_entities
    utils.get_cru_file
    utils.get_histalp_file
    utils.get_ref_mb_glaciers


Entity tasks

Entity tasks are tasks which are applied on single glaciers individually and do not require information from other glaciers (this encompasses the majority of OGGM's tasks). They are parallelizable.

.. autosummary::
    :toctree: generated/
    :nosignatures:

    tasks.define_glacier_region
    tasks.glacier_masks
    tasks.compute_centerlines
    tasks.initialize_flowlines
    tasks.compute_downstream_line
    tasks.compute_downstream_bedshape
    tasks.catchment_area
    tasks.catchment_intersections
    tasks.catchment_width_geom
    tasks.catchment_width_correction
    tasks.process_cru_data
    tasks.process_histalp_data
    tasks.process_custom_climate_data
    tasks.process_gcm_data
    tasks.process_cesm_data
    tasks.process_cmip5_data
    tasks.local_t_star
    tasks.mu_star_calibration
    tasks.apparent_mb_from_linear_mb
    tasks.glacier_mu_candidates
    tasks.prepare_for_inversion
    tasks.mass_conservation_inversion
    tasks.filter_inversion_output
    tasks.distribute_thickness_per_altitude
    tasks.distribute_thickness_interp
    tasks.init_present_time_glacier
    tasks.run_random_climate
    tasks.run_constant_climate
    tasks.run_from_climate_data

Global tasks

Global tasks are tasks which are run on a set of glaciers (most often: all glaciers in the current run). They are not parallelizable at the user level but might use multiprocessing internally.

.. autosummary::
    :toctree: generated/
    :nosignatures:

    tasks.compute_ref_t_stars
    tasks.compile_glacier_statistics
    tasks.compile_run_output
    tasks.compile_climate_input
    tasks.compile_task_log

Classes

Listed here are the classes which are relevant at the API level (i.e. classes which are used and re-used across modules and tasks).

.. autosummary::
    :toctree: generated/
    :nosignatures:

    GlacierDirectory
    Centerline
    Flowline

Glacier directories

Glacier directories (see also: :py:class:`~oggm.GlacierDirectory`) are folders on disk which store the input and output data for a single glacier during an OGGM run. The data are on disk to be persistent, i.e. they won't be deleted unless you ask OGGM to. You can start a run from an existing directory, avoiding to re-do unnecessary computations.

Initialising a glacier directory

The easiest way to initialize a glacier directory is to start from a pre-processed state available on the OGGM servers:

.. ipython:: python

    import os
    import oggm
    from oggm import cfg, workflow
    from oggm.utils import gettempdir
    cfg.initialize()  # always initialize before an OGGM task
    # The working directory is where OGGM will store the run's data
    cfg.PATHS['working_dir'] = os.path.join(gettempdir(), 'Docs_GlacierDir')
    gdirs = workflow.init_glacier_regions('RGI60-11.00897', from_prepro_level=1,
                                          prepro_border=10)
    gdir = gdirs[0]  # init_glacier_regions always returns a list


We just downloaded the minimal input for a glacier directory. The GlacierDirectory object contains the glacier metadata:

.. ipython:: python

    gdir
    gdir.rgi_id

It also points to a specific directory in disk, where the files are written to:

.. ipython:: python

    gdir.dir
    os.listdir(gdir.dir)

Users usually don't have to care about where the data is located. GlacierDirectory objects help you to get this information:

.. ipython:: python

    fdem = gdir.get_filepath('dem')
    fdem
    import xarray as xr
    @savefig plot_gdir_dem.png width=80%
    xr.open_rasterio(fdem).plot(cmap='terrain')

This persistence on disk allows for example to continue a workflow that has been previously interrupted. Initialising a GlacierDirectory from a non-empty folder won't erase its content:

.. ipython:: python

    gdir = oggm.GlacierDirectory('RGI60-11.00897')
    os.listdir(gdir.dir)  # the directory still contains the data


Mass-balance

Mass-balance models found in the core.massbalance module.

.. currentmodule:: oggm.core.massbalance

They follow the :py:func:`MassBalanceModel` interface. Here is a quick summary of the units and conventions used by all models:

Units

The computed mass-balance is in units of [m ice s-1] ("meters of ice per second"), unless otherwise specified (e.g. for the utility function get_specific_mb). The conversion from the climatic mass-balance ([kg m-2 s-1] ) therefore assumes an ice density given by cfg.PARAMS['ice_density'] (currently: 900 kg m-3).

Time

.. currentmodule:: oggm

The time system used by OGGM is a simple "fraction of year" system, where the floating year can be used for conversion to months and years:

.. ipython:: python

    from oggm.utils import floatyear_to_date, date_to_floatyear
    date_to_floatyear(1982, 12)
    floatyear_to_date(1.2)


Interface

.. currentmodule:: oggm.core.massbalance

.. autosummary::
    :toctree: generated/
    :nosignatures:

    MassBalanceModel
    MassBalanceModel.get_monthly_mb
    MassBalanceModel.get_annual_mb
    MassBalanceModel.get_specific_mb
    MassBalanceModel.get_ela

Models

.. autosummary::
    :toctree: generated/
    :nosignatures:

    LinearMassBalance
    PastMassBalance
    ConstantMassBalance
    RandomMassBalance
    UncertainMassBalance
    MultipleFlowlineMassBalance
You can’t perform that action at this time.