agrifoodpy

Submodules

Classes

FoodBalanceSheet

Common logic for for both data structures (DataArray and Dataset).

LandDataArray

XarrayAccessorBase

Common logic for for both data structures (DataArray and Dataset).

Package Contents

class agrifoodpy.FoodBalanceSheet(xarray_obj)

Bases: agrifoodpy.array_accessor.XarrayAccessorBase

Common logic for for both data structures (DataArray and Dataset).

http://xarray.pydata.org/en/stable/internals.html#extending-xarray

scale_element(element, scale, items=None)

Scales list of items from an element in a Food Balance Sheet like Dataset.

Parameters:

  • fbs (xarray.Dataset) – Input DataSet with FAOSTAT like elements

  • scale (float, float array_like or xarray.Dataarray) – Scaling quantities for the element DataArray

  • element (str) – Food Balance Sheet element to be scaled

  • items (list of int or list of str, optional) – List of items to be scaled. If not provided, all items are scaled.

Returns:

out – FAOSTAT formatted Food Supply dataset with scaled quantities.

Return type:

xarray.Dataset

scale_add(element_in, element_out, scale, items=None, add=True, elasticity=None)

Scales item quantities of an element and adds the difference to another element DataArray

Parameters:

  • fbs (xarray.Dataset) – Input DataSet with FAOSTAT like elements

  • element_in (str) – Element DataArray to be scaled

  • element_out (str) – Destination element DataArray to which the difference is added to

  • scale (float, float array_like or xarray.Dataarray) – Scaling quantities for the element DataArray

  • items (list of int or list of str, optional) – List of items to be scaled. If not provided, all items are scaled.

  • add (boolean) – Wether to add or subtract the difference to element_out

  • elasticity (float, float array_like optional) – Fractional percentage of the difference that is added to each element in element_out.

Returns:

out – FAOSTAT formatted Food Supply dataset with scaled quantities.

Return type:

xarray.Dataset

SSR(items=None, per_item=False, domestic=None, production='production', imports='imports', exports='exports')

Self-sufficiency ratio

Self-sufficiency ratio (SSR) or ratios for a list of item imports, exports and production quantities.

Parameters:

  • fbs (xarray.Dataset) – Input Dataset containing an “Item” coordinate and, optionally, a “Year” coordinate.

  • items (list, optional) – list of items to compute the SSR for from the food Dataset. If no list is provided, the SSR is computed for all items.

  • per_item (bool, optional) – Whether to return an SSR for each item separately. Default is false

  • domestic (string, optional) – Name of the DataArray containing the domestic use data

  • production (string, optional) – Name of the DataArray containing the production data

  • imports (string, optional) – Name of the DataArray containing the imports data

  • exports (string, optional) – Name of the DataArray containing the exports data

Returns:

data – Self-sufficiency ratio or ratios for the list of items, one for each year of the input food Dataset “Year” coordinate.

Return type:

xarray.Dataarray

IDR(items=None, per_item=False, imports='imports', domestic=None, production='production', exports='exports')

Import-dependency ratio

Import-ependency ratio (IDR) or ratios for a list of item imports, exports and production quantities.

Parameters:

  • fbs (xarray.Dataset) – Input Dataset containing an “Item” coordinate and, optionally, a “Year” coordinate.

  • items (list, optional) – list of items to compute the IDR for from the food Dataset. If no list is provided, the IDR is computed for all items.

  • per_item (bool, optional) – Whether to return an IDR for each item separately. Default is false.

  • domestic (string, optional) – Name of the DataArray containing the domestic use data

  • imports (string, optional) – Name of the DataArray containing the imports data

  • exports (string, optional) – Name of the DataArray containing the exports data

  • production (string, optional) – Name of the DataArray containing the production data

Returns:

data – Import-dependency ratio or ratios for the list of items, one for each year of the input food Dataset “Year” coordinate.

Return type:

xarray.Datarray

plot_bars(show='Item', elements=None, inverted_elements=None, ax=None, colors=None, labels=None, **kwargs)

Plot total quantities per element on a horizontal bar plot

Produces a horizontal bar plot with a bar per element on the vertical axis plotted on a cumulative form. Each bar is the sum of quantities on each element, broken down by the selected coordinate “show”. The starting x-axis position of each bar will depend on the cumulative value up to that element. The order of elements can be defined by the “element” parameter. A second set of “inverted_elements” can be given, and these will be plotted from right to left starting from the previous cumulative sum, minus the corresponding sum of the inverted elements.

Parameters:

  • show (str, optional) – Name of the coordinate to dissagregate when filling the horizontal bar. The quantities are summed along the remaining coordinates.

  • elements (str list, optional) – List of DataArray names in the Dataset to plot in ascending cumulative sum from left to right and top to bottom. If not provided, all DataArrays are plotted.

  • inverted_elements (strr list, optional) – List of DataArray names in the Dataset to plot in descending cumulative sum from right to left, and top to bottom. If not provided, none of the DataArray is used.

  • ax (matplotlib.pyplot.artist, optional) – Axes on which to draw the plot. If not provided, a new artist is created.

  • colors (list of str, optional) – String list containing the colors for each of the elements in the “show” coordinate. If not defined, a color list is generated from the standard cycling.

  • labels (str, list of str, optional) – String list containing the labels for the legend of the elements in the “show” coordinate. If not set, no labels are printed. If “show”, the values of the “show” dimension are used.

  • **kwargs (dict) – Style options to be passed on to the actual plot function, such as linewidth, alpha, etc.

Returns:

ax

Return type:

matplotlib axes instance

class agrifoodpy.LandDataArray(xarray_obj)
plot(ax=None, category_dim=None, colors=None, labels=None, legend=False, force_categorical=False, **kwargs)

Plot a LandDataArray

Generates a plot of a LandDataArray using matplotlib imshow, without interpolation and setting the origin low to align north at the top. If a dominant classification map type is provided, the plot will be coloured accordingly. If a class percentage map is provided, the plot will be coloured according to the dominant class on each pixel.

Parameters:

  • ax (matplotlib.pyplot.Artist) – Axes on which to draw the plot

  • category_dim (string) – Name of the dimension to use as land category. If not provided, the first non spatial dimension is used.

  • colors (list of strings) – Dictionary of colors to use for each land class. If not provided, the default matplotlib colour map is used.

  • labels (list of strings, dict) – List or dictionary of labels to use for each land class. If not provided and the map is a class percentage map, the coordinate values are used as labels.

  • legend (bool) – If True, and data is determined to be categorical, a legend is added to the plot. If data is not categorical, a colorbar is added instead.

  • **kwargs (dict) – Style options to be passed to the imshow function.

Returns:

ax

Return type:

matplotlib axes instance

area_by_type(values=None, dim=None)
area_by_category(categories=None, dim=None)

Area per map category in a LandDataArray

Returns a DataArray with the total number of pixels for each category or category subset of the LandDataArray.

Parameters:

  • categories (int, array) – List of categories to return the total area for. If not set, the function returns areas for all categories found on the map, excluding nan values.

  • dim (string) – Name to assign to the categories coordinate. If not set, the input DataArray name is used instead.

Returns:

Array with the corresponding areas overlaps for each category combination.

Return type:

xarray.DataArray

area_overlap(map_right, categories_left=None, categories_right=None, dim_left=None, dim_right=None, **kwargs)

Area overlap of selected categories between two maps

Returns a DataArray with the total number of pixels for each combination of categories from the left and right map selected categories.

Parameters:

  • map_right (xarray.DataArray) – LandDataArray style DataArray to compare overlapping areas with

  • categories_left (int, array) – List of land categories from the left map to return the total area overlaps for. If not set, all categories are used, except nan values.

  • categories_right (int, array) – List of land categories from the right map to return the total area overlaps for. If not set, all categories are used, except nan values.

  • dim_left (string) – Names to assign to the category coordinates on the output DataArray. If not set, the input DataArray name is used instead.

  • dim_right (string) – Names to assign to the category coordinates on the output DataArray. If not set, the input DataArray name is used instead.

Returns:

area_arr – Array with the corresponding areas for each category type

Return type:

xarray.DataArray

category_match(map_right, categories_left=None, categories_right=None, join='left', **kwargs)

Returns a land Dataarray with values where a selected overlap occurs between categories from two maps. This returns the values from the left map where coincidence occurs between the left and right map.

Parameters:

  • map_right (xarray.DataArray) – LandDataArray style DataArray to compare overlapping areas with

  • values_left (int, array) – List of category types from the left map to match. If not set, all category types are used, except nan values.

  • values_right (int, array) – List of category types from the right map to match. If not set, all category types are used, except nan values.

Returns:

category_match – Land DataArray with values from the left map where overlap occurs. All other positions are assign a nan value.

Return type:

xarray.DataArray

dominant_class(class_coord=None, return_index=False, **kwargs)
dominant_category(category_dim=None, return_index=False, **kwargs)

Returns a land DataArray with the dominant land class for each pixel.

Parameters:

  • category_dim (string) – Name of the land class coordinate. If not set, the first coordinate is used.

  • return_index (bool) – If True, the index of the dominant class is returned instead of the class value.

Returns:

Land DataArray with the dominant land class for each pixel.

Return type:

xarray.DataArray

add_category(category, category_value=0, mask=None, category_dim=None)

Add a new land category to a LandDataArray

Parameters:

  • category (string, list of strings) – Name of the land class coordinate to add. Cannot contain values already present in the LandDataArray, or duplicated within the input list.

  • category_value (int, xarray.DataArray) – Value of the new land class to add. If an array is provided, it must have the same shape as the spatial dimensions of the LandDataArray.

  • mask (xarray.DataArray) – Boolean DataArray with the same spatial dimensions as the LandDataArray indicating where to add the new category. If not provided, the new category is added to all pixels.

  • category_dim (string) – Name of the land class dimension. If not set, the first non spatial dimension is used.

Returns:

Land DataArray with the new land category added.

Return type:

xarray.DataArray

class agrifoodpy.XarrayAccessorBase(xarray_obj)

Bases: object

Common logic for for both data structures (DataArray and Dataset).

http://xarray.pydata.org/en/stable/internals.html#extending-xarray

add_items(items, copy_from=None)

Extends the item list of an input xarray object according to the defined input item list

Parameters:

  • items (list, int, string) – list of item names to be added to the data

  • copy_from (list, int, string, optional) – If provided, this is the list of items already on the array to copy data from.

Returns:

out – Xarray object with new items added.

Return type:

xarray.Dataset, xarray.DataArray

add_regions(regions, copy_from=None)

Extends the region list of an input xarray object according to the defined input region list

Parameters:

  • regions (list, int, string) – list of region names to be added to the data

  • copy_from (list, int, string) – If provided, this is the list of regions already on the object to copy data from.

  • labels (dict) – Dictionary containing the new label for the regions matched to its corresponding label coordinate.

Returns:

out – Xarray object with new regions added.

Return type:

xarray.Dataset, xarray.DataArray

add_years(years, pivot_year=None, projection='empty')

Adds or extends the Year coordinate of an xarray object

Parameters:

  • years (list, int) – list of years to be added to the data

  • pivot_year (int, optional) – Year to use as a pivot for the projection. If not provided, the last year of the input array is used.

  • projection (string or array_like) – Projection mode. If “constant”, the last year of the input array is copied to every new year. If “empty”, values are initialized and set to NaN. If a float array is given, these are used to populate the new year using a scaling of the last year of the array

Returns:

out – Xarray object with new years added.

Return type:

xarray.Dataset, xarray.DataArray

group_sum(coordinate, new_name=None)

Sums quantities over items of a equal group labels and, optionally, renames the groups label coordinate.

Parameters:

  • fbs (xarray.Dataset) – Input xarray object

  • coordinate (string) – Coordinate name to group elements and sum over

  • new_name (string, optional) – New name for the collapsed coordinate

Returns:

fbs – Xarray object with new coordinate base.

Return type:

xarray.Dataset, xarray.DataArray