New OGGM_Edu interface (#133)

* Initial idea of the glacier class and notebook for explanation.

* Added temporary requirements. Remember to remove this later.

* Add GlacierBed

This adds the GlacierBed class, an object for storing information about
the glacier bed. Initialisation can be done in two ways: Either with
single scalars for top, bottom and width or with altitude/width pairs
for greater control of the geometry. Also changes the glacier class to
accept the bed for initalisaiton.

Also contains some changes to the
plotting.

* Update the glacier collection to work with changes introduced wit the GlacierBed class.

* Update the WIP notebook to use `GlacierBed`.

* Glacier history implementation

Changes how the glacier is simulated (progresssed)
- Now using `run_until_and_store`, enables saving some diagnostics of
  the glacier.
- New history attribute of the glacier, dataset with glacier attributes.
- Diagnostics are appended as the glacier is progressed further.
- Change names of `grow_until_....` to `progress_until...` for both the
  glacier and the collection.
- New `plot_history` method for both glacier and collection.
- Small visual improvements of plots.

* Update WIP notebook to use new functionality:
- History plots
- Naming convention: grow = progress.

* Updated requirements

* Updated and revised documentation.

* Added ability to create a new glacier based on an already existing
glacier. It basically copies the attributes from the provided glacier
object.

* Quality of life improvements to the GlacierBed and Glacier class.

- Now possible to specify the slope of the glacier bed. This is done as
  decimal percentage for now. But could be changed to degrees in the
  future. Basically changes the grid point distance. Maybe this should
  include a warning for very flat glaciers since grid point spacing will
  become very large. Not possible to set to 0.

- Now exposing the glen_a creep parameter and basal sliding parameters
  as glaciers attributes. Possible to change just as other attributes.
  But these have sane defaults, so can be left untouched. These should
  maybe raise a warning when user tries to set them to unreasonable
  values.

* Added logic to `GlacierCollection.add()` to also be able to handle a
list (array) of glaciers.

* Update the WIP notebook to show latest functionality

- Copy a glacier.
- Assign the bed slope.
- Basal sliding.
- Adding a list of glaciers to the `GlacierCollection`

* Minor plot enhancements.

* Implementation of the SurgingGlacier class.

This adds the SurgingGlacier class, an extension of the Glacier class.
It provides some new attributes:
- normal_years
- sliding_years
- basal_sliding_surge

It overrides the progress_to_year method to deal with surging.
progress_to_equilibrium will raise an NotImplementedError.

* SurgingGlacier history plot

 This add some extra decorations to the plot_history method of the
 SurgingGlacier class. To make this a bit nicer, the Glacier class now
 instead has a _create_history_plot_components method and plot_history
 method. Here one method creates the components of the plot and one
 method draws the components. This way we can add some extra elements to
 a plot without having to re-write the same code for the base.

* Update SurgingGlacier.progress_to_year to allow for breaking in the
middle of a period. Before we couldn't stop in the middle of a period
and then start there again while keeping the surging cycle. Now this
works.

* Add surging glacier example.

* Small update to surging example.

* Small intro update.

* Small updates to representation and where the ELA is placed in the top
view of the glacier. Now placed where the glacier surface is matching
the ELA.

* Small change to the history ds combination. Fixes the problem with the
intersecting years being duplicated in the resulting ds.

* MassBalance class and temperature bias scenario

First implementation of the MassBalance class and changes relevant to
make the temperature bias scenarios possible. MassBalance class contains
methods to update the temperature bias annually during progression and
how to set the temperature bias evolution. The latter is accessed
through the glacier object. This also includes some changes to how the
progress methods works internally.

* Update notebook to show the MassBalance class and how an climate change
scenario can be accomplished.

* Update SurgingGlacier to use the mass_balance attribute instead of mb_model.

* Updated .gitignore

* Addition of the response time and eq_states attributes to the glacier.

* Added example of use of the reponse time.

* New copy mechanism for the glacier object.

* Update to the representation of glacier,bed, and mass balance.

* Updates to the GlacierCollection. Now has a pretty html representation
borrowed from a pandas dataframe. Adding a glacier also now checks if it
exist in the collection already.

* Update notebook.

* Html representations for GlacierBed,MassBalance and Glacier.

* Refactor. Placing classes in separate modules, e.g. Glacier and
SurgingGlacier in glacier, GlacierBed in glacierBed, MassBalance in
massBalance and GlacierCollection in glacierCollection.

* Small doc. correction.

* Methods to fill collection and batch change attributes of glaciers in
the collection.

* Fix error in ELA annotation in plot method of collection.

* Update notebook with new features. Fill and change_attributes to
Collection.

* Split bed plot method into two components to make it possible to re-use
some of the parts for other plots.

* Implements a new attribute holding the state history of the glacier.
Some small changes to the run_to methods. Also includes a method to plot
the states.

* Add new state_history functionality.

* Better composition of Glacier plotting method. Now uses the bed to
create the base plot.

* Refinements to plot_state_history. Now also include functionality to
plot the equilibrium states by setting the argument eq_states to True.

* Adds a new namespace for the old edu functions, now found under
legacy_functions. This will break previous usage of oggm_edu, hence
anything relying on oggm_edu functions either need to update import
statements or pin the version of oggm_edu.

* Update notebook for plot_state_history.

* Remove wip notebook.

* Changed behaviour of `.plot_history` when the glacier has no history. It
now creates an empty plot and prints a message that the glacier has no
history, instead of raising an error.

* Small update to collection plotting routines. Glacier indices now match
in representation and plot legend.

* Add proper property and setters for ELA and gradient to the mass balance
object. Update the change_attribute method of the collection to use
these.

* Small update to mass balance and a method for plotting mass balances of
a collection.

* Add response time to the representation of the glacier.

* Update to stop_function in the progress_to_equilibrium. User can pass
t_rate now. Set to 0.0001 as default. Previously 0.001, this did not
work for glacier with a very low mb gradient. Expose inner
progress_to_equilibrium args. in collection.progress_to_equilibrium.

* Small updates to SurgingGlacier
- Representation
- Different default for basal_sliding during non-surge periods.
- Add bed and mass_balance arguments to initialiser and passing to
  Glacier init.

* Html representation changes and grid.
- Changes how the html representation is generated. Use pandas concat
  instead of append. Treats missing/extra columns better.

* Add specific mass balance attribute and change the annual mass balance to
an attribute.

* Updates to eq_states. Now also stores the ELA at time of eq. Adds ELA
lines to eq_state plot method.

* Begin of some refactoring

* Adopt black code formatting.

* Rename modules
- glacierBer -> glacier_bed
- glacierCollection -> glacier_collection
- massBalance -> mass_balance

Also updates relevant import statements.

* Change any attributes with ELA to ela and the references. Also update
signature for the MassBalance init.

* Add plotting decorator to relevant methods.

* Some more input from Fabi

* Small quality and bug fix.

* Revert MassBalance logic.

* Reworked Edu MassBalance

The Edu MassBalance is now a full oggm.MassBalanceModel on its own. It
implement its own get_monthly_mb and get_annual_mb along with extensions
existing in the previous edu.MassBalance.

It is now possible to specify a mass balance with any number of
gradients by supplying the constructor with multiple gradients and
altitude breakpoints between them.

All changes are internal so no changes are needed for compatibility.

* Add some tests for mass_balance.

* Remove setters for mb attributes.

The glacier can no longer change or add attributes in the MassBalance,
only view them. Hence the mass_balance is no longer optional for
initialisation.

* Tests for glacier_bed.

Adds tests for the GlacierBed constructor, attributes and the
_create_base_plot.

* Some tests for Glacier and SurgingGlacier.

* Test the glacier collection.

Adds tests to both functionality and visuals of the GlacierCollection.
- Make sure we can add glaciers as intended: add, fill, through
  constructor. And that these throw when something is done wrong.
- Change attributes of the glaciers in the collection.
- Figures produced by class method should stay consistent.

* Glacier: copy of bed and mass balance.

Previously a glacier simply referenced the bed and glacier objects
passed at construction. This can cause some problems if multiple
glaciers are initialised from one set of bed and mass balance. When the
user then change an attribute of the mass balance through the glacier
object, this would cascade to all glacier based on that mass balance.
Now the glacier simply creates a copy of the bed and mass
balance, isolating them.

* Small correction of constructor logic.

Should throw if top OR bottom is below zero.

* Update collections import.

Sequence should be imported from collections.abc.

* Glacier.progress_to_year logic update.

No longer need to check if we have a mass balance any more since the
mass balance is now required at init.

Co-authored-by: Fabien Maussion <fabien.maussion@uibk.ac.at>

.gitignore

@@ -35,3 +35,6 @@ docs/generated
 docs/_sources
 docs/_images
 docs/.doctrees
+
+# Etc.
+.vim

oggm_edu/__init__.py

@@ -1,3 +1,10 @@
-__version__ = '0.0.1'
+__version__ = "0.1.0b"
 
-from .funcs import *
+from oggm_edu.funcs import plot_glacier_graphics, initalize_oggm
+from oggm_edu.glacier import Glacier, SurgingGlacier
+from oggm_edu.glacier_bed import GlacierBed
+from oggm_edu.glacier_collection import GlacierCollection
+from oggm_edu.mass_balance import MassBalance
+
+# Initialize on import
+initalize_oggm()