Urban Cooling Model.

natcap.invest.urban_cooling_model.calc_cc_op_factors(shade_array, albedo_array, eti_array, cc_weight_shade, cc_weight_albedo, cc_weight_eti)

Calculate the cooling capacity index using weighted factors.

  • shade_array (numpy.ndarray) – array of shade index values 0..1

  • albedo_array (numpy.ndarray) – array of albedo index values 0..1

  • eti_array (numpy.ndarray) – array of evapotransipration index values 0..1

  • cc_weight_shade (float) – 0..1 weight to apply to shade

  • cc_weight_albedo (float) – 0..1 weight to apply to albedo

  • cc_weight_eti (float) – 0..1 weight to apply to eti


CC_i = ((cc_weight_shade * shade) +

(cc_weight_albedo * albedo) + (cc_weight_eti * ETI))


Calculate the cooling capacity index using building intensity.


intensity_array (numpy.ndarray) – array of intensity values.


A numpy array of 1 - intensity_array.

natcap.invest.urban_cooling_model.calc_eti_op(kc_array, kc_nodata, et0_array, et0_nodata, et_max, target_nodata)

Calculate ETI = (K_c * ET_0) / ET_max.

natcap.invest.urban_cooling_model.calc_t_air_nomix_op(t_ref_val, hm_array, uhi_max)

Calculate air temperature T_(air,i)=T_ref+(1-HM_i)*UHI_max.

  • t_ref_val (float) – The user-defined reference air temperature in degrees Celsius.

  • hm_array (numpy.ndarray) – The calculated Heat Mitigation index from equation 5 in the User’s Guide.

  • uhi_max (float) – The user-defined maximum UHI magnitude.


A numpy array with the same dimensions as hm_array with the calculated T_air_nomix values.

natcap.invest.urban_cooling_model.calculate_energy_savings(t_air_stats_pickle_path, t_ref_raw, uhi_max, energy_consumption_table_path, base_building_vector_path, target_building_vector_path)

Calculate energy savings.

Energy savings is calculated from equations 8 or 9 in the User’s Guide (depending on whether a cost has been provided in the energy consumption table).

  • t_air_stats_pickle_path (str) – path to t_air zonal stats indexed by FID.

  • t_ref_raw (float) – single value for Tref.

  • uhi_max (float) – UHI max parameter from documentation.

  • energy_consumption_table_path (str) – path to energy consumption table that contains at least the columns ‘type’, and ‘consumption’. If the table also contains a ‘cost’ column, the output energy savings field will be multiplied by the floating-point cost provided in the ‘cost’ column.

  • base_building_vector_path (str) – path to existing vector to copy for the target vector that contains at least the field ‘type’.

  • target_building_vector_path (str) – path to target vector that will contain the additional field ‘energy_sav’ calculated as consumption.increase(b) * ((T_(air,MAX)  - T_(air,i))). This vector must be in a linearly projected spatial reference system.



natcap.invest.urban_cooling_model.calculate_uhi_result_vector(base_aoi_path, t_ref_val, t_air_stats_pickle_path, cc_stats_pickle_path, wbgt_stats_pickle_path, light_loss_stats_pickle_path, heavy_loss_stats_pickle_path, energy_consumption_vector_path, target_uhi_vector_path)

Summarize UHI results.

Output vector will have fields with attributes summarizing:
  • average cc value

  • average temperature value

  • average temperature anomaly

  • avoided energy consumption

  • base_aoi_path (str) – path to AOI vector.

  • t_ref_val (float) – reference temperature.

  • wbgt_stats_pickle_path (str) – path to pickled zonal stats for wbgt. Can be None if no valuation occurred.

  • light_loss_stats_pickle_path (str) – path to pickled zonal stats for light work loss. Can be None if no valuation occurred.

  • heavy_loss_stats_pickle_path (str) – path to pickled zonal stats for heavy work loss. Can be None if no valuation occurred.

  • energy_consumption_vector_path (str) – path to vector that contains building footprints with the field ‘energy_sav’. Can be None if no valuation occurred.

  • target_uhi_vector_path (str) –

    path to UHI vector created for result. Will contain the fields:

    • avg_cc

    • avg_tmp_an

    • avd_eng_cn

    • average WBGT

    • average light loss work

    • average heavy loss work



natcap.invest.urban_cooling_model.calculate_wbgt(avg_rel_humidity, t_air_raster_path, target_vapor_pressure_path)

Raster calculator op to calculate wet bulb globe temperature.

  • avg_rel_humidity (float) – number between 0-100.

  • t_air_raster_path (string) – path to T air raster.

  • target_vapor_pressure_path (string) – path to target vapor pressure raster.


WBGT_i = 0.567 * T_(air,i) + 0.393 * e_i + 3.94

where e_i:

e_i = RH/100*6.105*exp(17.27*T_air/(237.7+T_air))

natcap.invest.urban_cooling_model.convolve_2d_by_exponential(decay_kernel_distance, signal_raster_path, target_convolve_raster_path)

Convolve signal by an exponential decay of a given radius.

  • decay_kernel_distance (float) – radius of 1/e cutoff of decay kernel raster in pixels.

  • signal_rater_path (str) – path to single band signal raster.

  • target_convolve_raster_path (str) – path to convolved raster.




Urban Cooling.

  • args['workspace_dir'] (str) – path to target output directory.

  • args['results_suffix'] (string) – (optional) string to append to any output file names

  • args['t_ref'] (str/float) – reference air temperature.

  • args['lulc_raster_path'] (str) – path to landcover raster. This raster must be in a linearly-projected CRS.

  • args['ref_eto_raster_path'] (str) – path to evapotranspiration raster.

  • args['aoi_vector_path'] (str) – path to desired AOI.

  • args['biophysical_table_path'] (str) – table to map landcover codes to Shade, Kc, and Albedo values. Must contain the fields ‘lucode’, ‘kc’, and ‘green_area’. If args['cc_method'] == 'factors', then this table must also contain the fields ‘shade’ and ‘albedo’. If args['cc_method'] == 'intensity', then this table must also contain the field ‘building_intensity’.

  • args['green_area_cooling_distance'] (float) – Distance (in m) over which large green areas (> 2 ha) will have a cooling effect.

  • args['t_air_average_radius'] (float) – radius of the averaging filter for turning T_air_nomix into T_air.

  • args['uhi_max'] (float) – Magnitude of the UHI effect.

  • args['do_energy_valuation'] (bool) – if True, calculate energy savings valuation for buildings.

  • args['do_productivity_valuation'] (bool) – if True, calculate work productivity valuation based on humidity and temperature.

  • args['avg_rel_humidity'] (float) – (optional, depends on ‘do_productivity_valuation’) Average relative humidity (0-100%).

  • args['building_vector_path'] – (str) (optional, depends on ‘do_energy_valuation’) path to a vector of building footprints that contains at least the field ‘type’.

  • args['energy_consumption_table_path'] (str) – (optional, depends on ‘do_energy_valuation’) path to a table that maps building types to energy consumption. Must contain at least the fields ‘type’ and ‘consumption’.

  • args['cc_method'] (str) – Either “intensity” or “factors”. If “intensity”, then the “building_intensity” column must be present in the biophysical table. If “factors”, then args['cc_weight_shade'], args['cc_weight_albedo'], args['cc_weight_eti'] may be set to alternative weights if desired.

  • args['cc_weight_shade'] (str/float) – floating point number representing the relative weight to apply to shade when calculating the cooling index. Default: 0.6

  • args['cc_weight_albedo'] (str/float) – floating point number representing the relative weight to apply to albedo when calculating the cooling index. Default: 0.2

  • args['cc_weight_eti'] (str/float) – floating point number representing the relative weight to apply to ETI when calculating the cooling index. Default: 0.2



natcap.invest.urban_cooling_model.hm_op(cc_array, green_area_sum, cc_park_array, green_area_threshold)

Calculate HM.

cc_array (numpy.ndarray): this is the raw cooling index mapped from

landcover values.

green_area_sum (numpy.ndarray): this is the sum of green space pixels

pixels within the user defined area for green space.

cc_park_array (numpy.ndarray): this is the exponentially decayed

cooling index due to proximity of green space.

green_area_threshold (float): a value used to determine how much

area is required to trigger a green area overwrite.


cc_array if green area < green_area_threshold or cc_park < cc array, otherwise cc_park array is returned.

natcap.invest.urban_cooling_model.map_work_loss(work_temp_threshold_array, temperature_raster_path, work_loss_raster_path)

Map work loss due to temperature.

  • work_temp_threshold_array (list) – list of 3 sorted floats indicating the thresholds for 25, 50, and 75% work loss.

  • temperature_raster_path (string) – path to temperature raster in the same units as work_temp_threshold_array.

  • work_loss_raster_path (string) – path to target raster that maps per pixel work loss percent.



natcap.invest.urban_cooling_model.pickle_zonal_stats(base_vector_path, base_raster_path, target_pickle_path)

Calculate Zonal Stats for a vector/raster pair and pickle result.

  • base_vector_path (str) – path to vector file

  • base_raster_path (str) – path to raster file to aggregate over.

  • target_pickle_path (str) – path to desired target pickle file that will be a pickle of the pygeoprocessing.zonal_stats function.