Ctrl+K

climada_petals.entity.exposures package

climada_petals.entity.exposures package#

climada_petals.entity.exposures.black_marble module#

class climada_petals.entity.exposures.black_marble.BlackMarble(*args, meta=None, description=None, ref_year=2018, value_unit='USD', crs=None, **kwargs)[source]#

Bases: Exposures

Defines exposures from night light intensity, GDP and income group. Attribute region_id is defined as: - United Nations Statistics Division (UNSD) 3-digit equivalent numeric code - 0 if country not found in UNSD. - -1 for water

set_countries(countries, ref_year=2016, res_km=None, from_hr=None, admin_file='admin_0_countries', **kwargs)[source]#

Model countries using values at reference year. If GDP or income group not available for that year, consider the value of the closest available year.

Parameters:

  • countries (list or dict) – list of country names (admin0 or subunits) or dict with key = admin0 name and value = [admin1 names]

  • ref_year (int, optional) – reference year. Default: 2016

  • res_km (float, optional) – approx resolution in km. Default: nightlights resolution.

  • from_hr (bool, optional) – force to use higher resolution image, independently of its year of acquisition.

  • admin_file (str) – file name, admin_0_countries or admin_0_map_subunits

  • kwargs (optional) – ‘gdp’ and ‘inc_grp’ dictionaries with keys the country ISO_alpha3 code. ‘poly_val’ list of polynomial coefficients [1,x,x^2,…] to apply to nightlight (DEF_POLY_VAL used if not provided). If provided, these are used.

climada_petals.entity.exposures.crop_production module#

climada_petals.entity.exposures.crop_production.DEF_HAZ_TYPE = 'RC'#

Default hazard type used in impact functions id.

climada_petals.entity.exposures.crop_production.BBOX = (-180, -85, 180, 85)#

“Default geographical bounding box of the total global agricultural land extent

climada_petals.entity.exposures.crop_production.YEARCHUNKS = {'ISIMIP2': {'1860soc': {'endyear': 1860, 'startyear': 1661, 'yearrange': (1800, 1860)}, '2005soc': {'endyear': 2299, 'startyear': 2006, 'yearrange': (2006, 2099)}, '2100rcp26soc': {'endyear': 2299, 'startyear': 2100, 'yearrange': (2100, 2299)}, 'histsoc': {'endyear': 2005, 'startyear': 1861, 'yearrange': (1976, 2005)}, 'rcp26soc': {'endyear': 2099, 'startyear': 2006, 'yearrange': (2006, 2099)}, 'rcp60soc': {'endyear': 2099, 'startyear': 2006, 'yearrange': (2006, 2099)}}, 'ISIMIP3': {'2015soc': {'endyear': 2014, 'startyear': 1850, 'yearrange': (1983, 2013)}, 'histsoc': {'endyear': 2014, 'startyear': 1850, 'yearrange': (1983, 2013)}}}#

start and end years per ISIMIP version and senario as in ISIMIP-filenames of landuse data containing harvest area per crop

climada_petals.entity.exposures.crop_production.FN_STR_VAR = 'landuse-15crops_annual'#

fix filename part in input data

climada_petals.entity.exposures.crop_production.CROP_NAME = {'mai': {'fao': 'Maize', 'input': 'maize', 'print': 'Maize'}, 'ri1': {'fao': 'Rice, paddy', 'input': 'rice', 'print': 'Rice 1st season'}, 'ri2': {'fao': 'Rice, paddy', 'input': 'rice', 'print': 'Rice 2nd season'}, 'ric': {'fao': 'Rice, paddy', 'input': 'rice', 'print': 'Rice'}, 'soy': {'fao': 'Soybeans', 'input': 'oil_crops_soybean', 'print': 'Soybeans'}, 'swh': {'fao': 'Wheat', 'input': 'temperate_cereals', 'print': 'Spring Wheat'}, 'whe': {'fao': 'Wheat', 'input': 'temperate_cereals', 'print': 'Wheat'}, 'wwh': {'fao': 'Wheat', 'input': 'temperate_cereals', 'print': 'Winter Wheat'}}#

mapping of crop names

climada_petals.entity.exposures.crop_production.IRR_NAME = {'combined': {'name': 'combined'}, 'firr': {'name': 'irrigated'}, 'noirr': {'name': 'rainfed'}}#

Conversion factor weight [tons] to nutritional value [kcal]. Based on Mueller et al. (2021), https://doi.org/10.1088/1748-9326/abd8fc :

“For the aggregation of different crops, we compute total calories, assuming net water contents of 12% for maize, spring and winter wheat, 13% for rice and 9% for soybean, according to Wirsenius (2000) and caloric contents of the “as purchased” biomass (i.e. including the water content) of 3.56kcal/g for maize, 2.8kcal/g for rice, 3.35kcal/g for soybean and of 3.34kcal/g for spring and winter wheat, following FAO (2001).” (Müller et al., 2021)

Version 1: conversion factors for crop biomass “as purchased”,

here applied as default for FAO-normalized production: Production [kcal] = Production [t] * KCAL_PER_TON [kcal/t]

climada_petals.entity.exposures.crop_production.YEARS_FAO = (2008, 2018)#

Default years from FAO used (data file contains values for 1991-2018)

class climada_petals.entity.exposures.crop_production.CropProduction(*args, meta=None, description=None, ref_year=2018, value_unit='USD', crs=None, **kwargs)[source]#

Bases: Exposures

Defines agriculture exposures from ISIMIP input data and FAO crop data

geopandas GeoDataFrame with metadata and columns (pd.Series) defined in Attributes and Exposures.

crop#

crop typee.g., ‘mai’, ‘ric’, ‘whe’, ‘soy’

Type:

str

set_from_isimip_netcdf(*args, **kwargs)[source]#

This function is deprecated, use LitPop.from_isimip_netcdf instead.

classmethod from_isimip_netcdf(input_dir=None, filename=None, hist_mean=None, bbox=None, yearrange=None, cl_model=None, scenario=None, crop=None, irr=None, isimip_version=None, unit=None, fn_str_var=None)[source]#

Wrapper to fill exposure from NetCDF file from ISIMIP. Requires historical mean relative cropyield module as additional input.

Parameters:

  • input_dir (Path or str) – path to input data directory, default: {CONFIG.exposures.crop_production.local_data}/Input/Exposure

  • filename (string) – name of the landuse data file to use, e.g. “histsoc_landuse-15crops_annual_1861_2005.nc””

  • hist_mean (str or array) – historic mean crop yield per centroid (or path)

  • bbox (list of four floats) – bounding box: [lon min, lat min, lon max, lat max]

  • yearrange (int tuple) – year range for exposure set e.g., (1990, 2010)

  • scenario (string) – climate change and socio economic scenario e.g., ‘1860soc’, ‘histsoc’, ‘2005soc’, ‘rcp26soc’,’rcp60soc’,’2100rcp26soc’

  • cl_model (string) – abbrev. climate model (only for future projections of lu data) e.g., ‘gfdl-esm2m’, ‘hadgem2-es’, ‘ipsl-cm5a-lr’,’miroc5’

  • crop (string) – crop type e.g., ‘mai’, ‘ric’, ‘whe’, ‘soy’

  • irr (string) – irrigation type, default: ‘combined’ f.i ‘firr’ (full irrigation), ‘noirr’ (no irrigation) or ‘combined’= firr+noirr

  • isimip_version (str) – ‘ISIMIP2’ (default) or ‘ISIMIP3’

  • unit (string) – unit of the exposure (per year) f.i ‘t/y’ (default), ‘USD/y’, or ‘kcal/y’

  • fn_str_var (string) – FileName STRing depending on VARiable and ISIMIP simuation round

Return type:

Exposure

set_from_area_and_yield_nc4(*args, **kwargs)[source]#

This function is deprecated, use LitPop.from_area_and_yield_nc4 instead.

classmethod from_area_and_yield_nc4(crop_type, layer_yield, layer_area, filename_yield, filename_area, var_yield, var_area, bbox=(-180, -85, 180, 85), input_dir=PosixPath('/home/docs/climada/data/ISIMIP_crop/Input/Exposure'))[source]#

Set crop_production exposure from cultivated area [ha] and yield [t/ha/year] provided in two netcdf files with the same grid.

Both input files need to be netcdf format and come with dimensions ‘lon’, ‘lat’ and ‘crop’. The information which crop type is saved in which crop layer in each input files needs to be provided manually via the parameters ‘layer_*’.

A convenience wrapper around this expert method is provided with from_spam_ray_mirca().

Parameters:

  • crop_type (str) – Crop type, e.g. ‘mai’ for maize, or ‘ric’, ‘whe’, ‘soy’, etc.

  • layer_yield (int) – crop layer in yield input data set. Index typically starts with 1.

  • layer_area (int) – crop layer in area input data set. Index typically starts with 1.

  • filename_yield (str) – Name of netcdf-file containing gridded yield data. Requires coordinates ‘lon’, ‘lat’, and ‘crop’.

  • filename_area (str) – Name of netcdf-file containing gridded cultivated area. Requires coordinates ‘lon’, ‘lat’, and ‘crop’.

  • var_yield (str) – variable name to be extracted from yield file, e.g. ‘yield.rf’, ‘yield.ir’, ‘yield.tot’, or depending on netcdf structure.

  • var_area (str) – variable name to be extracted from area file, e.g. ‘cultivated area rainfed’, ‘cultivated area irrigated’, ‘cultivated area all’, or depending on netcdf structure.

  • bbox (tuple of four floats) (bounding box:) – bounding box to be extracted: (lon min, lat min, lon max, lat max). The default is (-180, -85, 180, 85).

  • input_dir (Path, optional) – directory where input data is found. The default is {CONFIG.exposures.crop_production.local_data}/Input/Exposure.

Returns:

crop production exposure instance based on yield and area data

Return type:

CropProduction

set_from_spam_ray_mirca(*args, **kwargs)[source]#

This function is deprecated, use CropPoduction.from_spam_ray_mirca instead.

classmethod from_spam_ray_mirca(crop_type, irrigation_type='all', bbox=(-180, -85, 180, 85), input_dir=PosixPath('/home/docs/climada/data/ISIMIP_crop/Input/Exposure'))[source]#

Wrapper method around from_area_and_yield_nc4().

Set crop_production exposure from cultivated area [ha] and yield [t/ha/year] provided in default input files. The default input files are based on the public yield data from SPAM2005 with gaps filled based on Ray et.al (2012); and cultivated area from MIRCA2000, both as post-processed by Jägermeyr et al. 2020; See https://doi.org/10.1073/pnas.1919049117 for more information and cite when using this data for publication.

Parameters:

  • crop_type (str) – Crop type, e.g. ‘mai’ for maize, or ‘ric’, ‘whe’, ‘soy’, etc.

  • irrigation_type (str, optional) – irrigation type to be extracted, the options are: ‘all’ : total crop production, i.e. irrigated + rainfed ‘firr’ : fully irrigated ‘noirr’ : not irrigated, i.e., rainfed The default is ‘all’

  • bbox (list of four floats) (bounding box:) – [lon min, lat min, lon max, lat max]

  • input_dir (Path, optional) – directory where input data is found. The default is {CONFIG.exposures.crop_production.local_data}/Input/Exposure.

Returns:

Crop production exposure based on SPAM and MIRCA data set

Return type:

Exposure

set_mean_of_several_isimip_models(*args, **kwargs)[source]#

This function is deprecated, use CropPoduction.from_mean_of_several_isimip_models instead.

classmethod from_mean_of_several_isimip_models(input_dir=None, hist_mean=None, bbox=None, yearrange=None, cl_model=None, scenario=None, crop=None, irr=None, isimip_version=None, unit=None, fn_str_var=None)[source]#

Wrapper to init exposure from several NetCDF files with crop yield data from ISIMIP.

Parameters:

  • input_dir (string) – path to input data directory

  • hist_mean (array) – historic mean crop production per centroid

  • bbox (list of four floats) – bounding box: [lon min, lat min, lon max, lat max]

  • yearrange (int tuple) – year range for exposure set,e.g., (1976, 2005)

  • scenario (string) – climate change and socio economic scenario e.g., ‘histsoc’ or ‘rcp60soc’

  • cl_model (string) – abbrev. climate model (only when landuse data is future projection) e.g., ‘gfdl-esm2m’ etc.

  • crop (string) – crop type e.g., ‘mai’, ‘ric’, ‘whe’, ‘soy’

  • irr (string) – irrigation type f.i ‘rainfed’, ‘irrigated’ or ‘combined’= rainfed+irrigated

  • isimip_version (str) – ‘ISIMIP2’ (default) or ‘ISIMIP3’

  • unit (string) – unit of the exposure (per year) f.i ‘t/y’ (default), ‘USD/y’, or ‘kcal/y’

  • fn_str_var (string) – FileName STRing depending on VARiable and ISIMIP simuation round

Return type:

Exposure

set_value_to_kcal(*args, **kwargs)[source]#

This function is deprecated, use function value_to_kcal instead.

set_value_to_usd(*args, **kwargs)[source]#

This function is deprecated, use functiom value_to_usd instead.

aggregate_countries()[source]#

Aggregate exposure data by country.

Returns:

  • list_countries (list) – country codes (numerical ISO3)

  • country_values (array) – aggregated exposure value

climada_petals.entity.exposures.crop_production.value_to_kcal(exp_cp, biomass=True)[source]#

Converts the exposure value from tonnes to kcal per year using conversion factor per crop type.

Parameters:

  • exp_cp (CropProduction) – CropProduction exposure object with units tonnes per year (‘t/y’)

  • biomass (bool, optional) – if true, KCAL_PER_TON[‘biomass’] is used (default, for FAO normalized crop production). If False, KCAL_PER_TON[‘drymatter’] is used (best for crop model output in dry matter, default for raw crop model output). Default: True

Returns:

new_exp – CropProduction exposure object with unit ‘kcal/y’

Return type:

CropProduction

climada_petals.entity.exposures.crop_production.value_to_usd(exp_cp, input_dir=None, yearrange=None)[source]#

Calculates the exposure in USD per year using country and year specific data published by the FAO, requires crop production exposure with unit ‘t/y’

Parameters:

  • exp_cp (CropProduction) – CropProduction exposure object with units tonnes per year (‘t/y’)

  • input_dir (Path or str, optional) – directory containing the input (FAO pricing) data, default: {CONFIG.exposures.crop_production.local_data}/Input/Exposure

  • yearrange (np.array, optional) – year range for prices, can also be set to a single year Default is set to the arbitrary time range (2000, 2018) The data is available for the years 1991-2018

  • crop (str) – crop type e.g., ‘mai’, ‘ric’, ‘whe’, ‘soy’

Returns:

new_exp – CropProduction exposure object with unit ‘USD/y’

Return type:

CropProduction

climada_petals.entity.exposures.crop_production.init_full_exp_set_isimip(input_dir=None, filename=None, hist_mean_dir=None, output_dir=None, bbox=None, yearrange=None, unit=None, isimip_version=None, return_data=False)[source]#
Generates CropProduction instances (exposure sets) for all files found in the

input directory and saves them as hdf5 files in the output directory. Exposures are aggregated per crop and irrigation type.

Parameters:

  • input_dir (str or Path) – path to input data directory, default: {CONFIG.exposures.crop_production.local_data}/Input/Exposure

  • filename (string) – if not specified differently, the file ‘histsoc_landuse-15crops_annual_1861_2005.nc’ will be used

  • output_dir (string) – path to output data directory

  • bbox (list of four floats) – bounding box: [lon min, lat min, lon max, lat max]

  • yearrange (array) – year range for hazard set, e.g., (1976, 2005)

  • isimip_version (str) – ‘ISIMIP2’ (default) or ‘ISIMIP3’

  • unit (str) – unit in which to return exposure (e.g., t/y or USD/y)

  • return_data (boolean) – returned output False: returns list of filenames only, True: returns also list of data

Returns:

  • filename_list (list) – all filenames of saved initiated exposure files

  • output_list (list) – list containing all inisiated Exposure instances

climada_petals.entity.exposures.crop_production.normalize_with_fao_cp(exp_firr, exp_noirr, input_dir=None, yearrange=None, unit=None, return_data=True)[source]#

Normalize (i.e., bias correct) the given exposures countrywise with the mean crop production quantity documented by the FAO. Refer to the beginning of the script for guidance on where to download the required crop production data from FAO.Stat.

Parameters:

  • exp_firr (crop_production) – exposure under full irrigation

  • exp_noirr (crop_production) – exposure under no irrigation

  • input_dir (Path or str) – directory containing exposure input data, default: {CONFIG.exposures.crop_production.local_data}/Input/Exposure

  • yearrange (array) – the mean crop production in this year range is used to normalize the exposure data Default is set to the arbitrary time range (2008, 2018) The data is available for the years 1961-2018

  • unit (str) – unit in which to return exposure (t/y or USD/y)

  • return_data (boolean) – returned output True: returns country list, ratio = FAO/ISIMIP, normalized exposures, crop production per country as documented by the FAO and calculated by the ISIMIP dataset False: country list, ratio = FAO/ISIMIP, normalized exposures

Returns:

  • country_list (list) – List of country codes (numerical ISO3)

  • ratio (list) – List of ratio of FAO crop production and aggregated exposure for each country

  • exp_firr_norm (CropProduction) – Normalized CropProduction (full irrigation)

  • exp_noirr_norm (CropProduction) – Normalized CropProduction (no irrigation)

  • Returns (optional)

  • fao_crop_production (list) – FAO crop production value per country

  • exp_tot_production (list) – Exposure crop production value per country (before normalization)

climada_petals.entity.exposures.crop_production.normalize_several_exp(input_dir=None, output_dir=None, yearrange=None, unit=None, return_data=True)[source]#

Multiple exposure sets saved as HDF5 files in input directory are normalized (i.e. bias corrected) against FAO statistics of crop production.

Parameters:

  • input_dir (Path or str) – directory containing exposure input data

  • output_dir (Path or str) – directory containing exposure datasets (output of exposure creation)

  • yearrange (array) – the mean crop production in this year range is used to normalize the exposure data (default 2008-2018)

  • unit (str) – unit in which to return exposure (t/y or USD/y)

  • return_data (boolean) – returned output True: lists containing data for each exposure file. Lists: crops, country list, ratio = FAO/ISIMIP, normalized exposures, crop production per country as documented by the FAO and calculated by the ISIMIP dataset False: lists containing data for each exposure file. Lists: crops, country list, ratio = FAO/ISIMIP, normalized exposures

Returns:

  • crop_list (list) – List of crops

  • country_list (list) – List of country codes (numerical ISO3)

  • ratio (list) – List of ratio of FAO crop production and aggregated exposure for each country

  • exp_firr_norm (list) – List of normalized CropProduction Exposures (full irrigation)

  • exp_noirr_norm (list) – List of normalize CropProduction Exposures (no irrigation)

  • fao_crop_production (list, optional) – FAO crop production value per country

  • exp_tot_production (list, optional) – Exposure crop production value per country (before normalization)

climada_petals.entity.exposures.crop_production.semilogplot_ratio(crop, countries, ratio, output_dir=None, save=True)[source]#

Plot ratio = FAO/ISIMIP against country codes.

Parameters:

  • crop (str) – crop to plot

  • countries (list) – country codes of countries to plot

  • ratio (array) – ratio = FAO/ISIMIP crop production data of countries to plot

  • save (boolean) – True saves figure, else figure is not saved.

  • output_dir (str) – directory to save figure

Returns:

  • fig (plt figure handle)

  • axes (plot axes handle)

climada_petals.entity.exposures.gdp_asset module#

class climada_petals.entity.exposures.gdp_asset.GDP2Asset(*args, meta=None, description=None, ref_year=2018, value_unit='USD', crs=None, **kwargs)[source]#

Bases: Exposures

set_countries(countries=[], reg=[], ref_year=2000, path=None)[source]#

Model countries using values at reference year. If GDP or income group not available for that year, consider the value of the closest available year.

Parameters:

  • countries (list) – list of country names ISO3

  • ref_year (int, optional) – reference year. Default: 2016

  • path (string) – path to exposure dataset (ISIMIP)

climada_petals.entity.exposures.spam_agrar module#

climada_petals.entity.exposures.spam_agrar.DEF_HAZ_TYPE = 'CP'#

Default hazard type used in impact functions id.

climada_petals.entity.exposures.spam_agrar.FILENAME_SPAM = 'spam2005V3r2_global'#

Add Docstring!

Type:

TODO

climada_petals.entity.exposures.spam_agrar.FILENAME_CELL5M = 'cell5m_allockey_xy.csv'#

Add Docstring!

Type:

TODO

Add Docstring!

Type:

TODO

climada_petals.entity.exposures.spam_agrar.BUFFER_VAL = -340282306073709652508363335590014353408#

Hard coded value which is used for NANs in original data

climada_petals.entity.exposures.spam_agrar.SPAM_URL = 'https://dataverse.harvard.edu/api/access/datafile/:persistentId?persistentId=doi:10.7910/DVN/DHXBJX/'#

URL stem for accessing data set files through api

climada_petals.entity.exposures.spam_agrar.SPAM_DATASET = 'https://dataverse.harvard.edu/dataset.xhtml?persistentId=doi:10.7910/DVN/DHXBJX'#

Data files can be downloaded from this location if api access fails

class climada_petals.entity.exposures.spam_agrar.SpamAgrar(*args, meta=None, description=None, ref_year=2018, value_unit='USD', crs=None, **kwargs)[source]#

Bases: Exposures

Defines agriculture exposures from SPAM (Global Spatially-Disaggregated Crop Production Statistics Data for 2005 Version 3.2 ) https://dataverse.harvard.edu/dataset.xhtml?persistentId=doi:10.7910/DVN/DHXBJX

Attribute region_id is defined as: - United Nations Statistics Division (UNSD) 3-digit equivalent numeric code - 0 if country not found in UNSD. - -1 for water

init_spam_agrar(**parameters)[source]#

initiates agriculture exposure from SPAM data:

https://dataverse.harvard.edu/ dataset.xhtml?persistentId=doi:10.7910/DVN/DHXBJX

Parameters:

  • data_path (str) – absolute path where files are stored. Default: SYSTEM_DIR

  • country (str) – Three letter country code of country to be cut out. No default (global)

  • name_adm1 (str) – Name of admin1 (e.g. Federal State) to be cut out. No default

  • name_adm2 (str) – Name of admin2 to be cut out. No default

  • spam_variable (str) – select one agricultural variable: ‘A’ physical area ‘H’ harvested area ‘P’ production ‘Y’ yield ‘V_agg’ value of production, aggregated to all crops, food and non-food (default) Warning: for A, H, P and Y, currently all crops are summed up

  • spam_technology (str) – select one agricultural technology type: ‘TA’ all technologies together, ie complete crop (default) ‘TI’ irrigated portion of crop ‘TH’ rainfed high inputs portion of crop ‘TL’ rainfed low inputs portion of crop ‘TS’ rainfed subsistence portion of crop ‘TR’ rainfed portion of crop (= TA - TI, or TH + TL + TS) ! different impact_ids are assigned to each technology (1-6)

  • save_name_adm1 (Boolean) – Determines how many aditional data are saved: False: only basics (lat, lon, total value), region_id per country True: like 1 + name of admin1

  • haz_type (str) – hazard type abbreviation, e.g. ‘DR’ for Drought or ‘CP’ for CropPotential

Contents