update diet matrix

Author: barriern

apecosm/mplot.py

@@ -20,7 +20,7 @@
 
 PROJIN = ccrs.PlateCarree()
 
-def plot_diet_values(data, const, community_index, legend_args={}, **kwargs):
+def plot_diet_values(diet_data, const, community_index, draw_legend=False, legend_args={}, **kwargs):
 
     community_names = extract_community_names(const)
     n_community = len(community_names)
@@ -31,14 +31,15 @@ def plot_diet_values(data, const, community_index, legend_args={}, **kwargs):
 
     ax = plt.gca()
     length = const['length'].isel(c=community_index)
-    diet = data['community_diet_values'].isel(c=community_index)#.compute()
+    diet = diet_data.isel(c=community_index)#.compute()
     repf = diet.sum(dim='prey_group')
     l = ax.stackplot(length, diet.T, edgecolor='k', **kwargs)
     ax.set_xscale('log')
     ax.set_xlim(length.min(), length.max())
     ax.set_ylim(0, repf.max())
     ax.set_title(community_names[community_index])
-    ax.legend(legend, **legend_args)
+    if draw_legend:
+        ax.legend(legend, **legend_args)
     return l
 
 def plot_oope_map(data, mesh, axis=None, draw_land=True, **kwargs):

doc/computations/diet.rst

@@ -7,6 +7,7 @@
     import apecosm
     import xarray as xr
     import matplotlib.pyplot as plt
+    import matplotlib
 
     domain_ds = xr.open_dataset(os.path.join('doc', 'data', 'domains.nc'))
     domain = domain_ds['domain_1']
@@ -18,11 +19,119 @@
     const = apecosm.open_constants(os.path.join('doc', 'data', 'apecosm/'))
     const
 
-    data = apecosm.open_apecosm_data(os.path.join('doc', 'data', 'apecosm'))
+    data = apecosm.open_apecosm_data(os.path.join('doc', 'data', 'apecosm'),
+                                     replace_dims={'community': 'c'})
     data
 
 **********************
 Diet calculation
 **********************
 
-If the Apecosm simulation has been
+If the diet outputs are available in the Apecosm
+simulations, it is possible to plot the diet matrix. This is
+achieved as follows.
+
+First, the spatial mean diet is computed using the
+:py:func:`apecosm.extract_weighted_data` function.
+
+.. ipython:: python
+
+    mean_diet = apecosm.extract_weighted_data(data, const, mesh, 'community_diet_values')
+    mean_diet
+
+.. ipython:: python
+    :suppress:
+
+    mean_diet = mean_diet.compute()
+
+Then, the time average is computed using the
+:py:func:`apecosm.extract_time_means` function:
+
+.. ipython:: python
+
+    time_average_mean_diet = apecosm.extract_time_means(mean_diet)
+    time_average_mean_diet
+
+.. ipython:: python
+    :suppress:
+
+    time_average_mean_diet = time_average_mean_diet.compute()
+
+Now, the drawing of the diet matrix is done by using the
+:py:func:`plot_diet_values` function:
+
+.. ipython:: python
+
+    fig = plt.figure()
+    ax = plt.gca()
+    l = apecosm.plot_diet_values(time_average_mean_diet, const, 0)
+    plt.savefig(os.path.join('doc', 'computations', '_static', 'diet_com_0.jpg'), bbox_inches='tight')
+    plt.savefig(os.path.join('doc', 'computations', '_static', 'diet_com_0.pdf'), bbox_inches='tight')
+    plt.close(fig)
+
+.. figure::  _static/diet_com_0.*
+    :align: center
+
+    Mean diet for community 0
+
+
+The first argument is the spatially and time averaged  diet matrix,
+the second argument is the dataset containing all the Apecosm constants
+and the third argument is the community index.
+
+Note that there is the possibility to control the legend layout by
+providing a `legend_args` argument, which is a dictionary containing
+the legend arguments.
+
+Furthermore, the arguments of the Matplotlib ``stackplot`` function
+can also be included in the   :py:func:`apecosm.plot_diet_values` function.
+
+For instance:
+
+.. ipython:: python
+
+    cmap = matplotlib.colormaps['jet']
+    colors = [cmap(i / 10) for i in range(11)]
+
+    fig = plt.figure()
+    ax = plt.gca()
+    l = apecosm.plot_diet_values(time_average_mean_diet, const, 0,
+                             colors=colors, alpha=0.5,
+                             legend_args={'ncol': 2, 'fontsize': 6})
+
+    plt.savefig(os.path.join('doc', 'computations', '_static', 'upt_diet_com_0.jpg'), bbox_inches='tight')
+    plt.savefig(os.path.join('doc', 'computations', '_static', 'upt_diet_com_0.pdf'), bbox_inches='tight')
+    plt.close(fig)
+
+.. figure::  _static/upt_diet_com_0.*
+    :align: center
+
+    Mean diet for community 0 with additional arguments for
+    controling the legend and stackplot display
+
+To draw the diet matrix for all communities, a loop
+must be done over the `c` dimension:
+
+.. ipython:: python
+
+    fig = plt.figure(figsize=(12, 8))
+    plt.subplots_adjust(hspace=0.5)
+
+    for c in range(5):
+        ax = plt.subplot(3, 2, c + 1)
+        draw_legend = (c == 0)
+        l = apecosm.plot_diet_values(time_average_mean_diet, const, c,
+                                     colors=colors, alpha=0.5, draw_legend=draw_legend,
+                                     legend_args={'ncol': 2, 'fontsize': 6, 'framealpha': 1})
+        ax.set_xlabel('Length (m)')
+        ax.set_xlim(const['length'].min(), const['length'].max())
+
+    plt.savefig(os.path.join('doc', 'computations', '_static', 'full_diet.jpg'), bbox_inches='tight')
+    plt.savefig(os.path.join('doc', 'computations', '_static', 'full_diet.pdf'), bbox_inches='tight')
+    plt.close(fig)
+
+.. figure::  _static/full_diet.*
+    :align: center
+
+    Mean diet for all communities with additional arguments for
+    controling the legend and stackplot display