natcap.invest.urban_cooling_model module¶
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.
- Parameters:
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
- Returns:
- CC_i = ((cc_weight_shade * shade) +
(cc_weight_albedo * albedo) + (cc_weight_eti * ETI))
- natcap.invest.urban_cooling_model.calc_cc_op_intensity(intensity_array)¶
Calculate the cooling capacity index using building intensity.
- Parameters:
intensity_array (numpy.ndarray) – array of intensity values.
- Returns:
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.
- Parameters:
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.
- Returns:
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).
- Parameters:
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.
- Returns:
None.
- 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
- Parameters:
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
- Returns:
None.
- 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.
- Parameters:
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.
- Returns:
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.
- Parameters:
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.
- Returns:
None.
- natcap.invest.urban_cooling_model.execute(args)¶
Urban Cooling.
- Parameters:
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’. Ifargs['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
- Returns:
None.
- 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.
- Returns:
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.
- Parameters:
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.
- Returns:
None.
- 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.
- Parameters:
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.
- Returns:
None.