Reference guide (API)¶

The InVEST urban cooling model calibration library provides two classes:

The UCMWrapper class is intended to provide a Pythonic and object-oriented interface to the urban cooling model which can be used to interactively experiment with the model (e.g., trying the results obtained with different parameters), and includes a set of additional useful methods.

class invest_ucm_calibration.UCMWrapper(lulc_raster_filepath, biophysical_table_filepath, cc_method, ref_et_raster_filepaths, *, aoi_vector_filepath=None, t_refs=None, uhi_maxs=None, t_raster_filepaths=None, station_t_filepath=None, station_locations_filepath=None, dates=None, workspace_dir=None, extra_ucm_args=None)¶

Pythonic and open source interface to the InVEST urban cooling model.

A set of additional utility methods serve to compute temperature maps and data frames.

__init__(lulc_raster_filepath, biophysical_table_filepath, cc_method, ref_et_raster_filepaths, *, aoi_vector_filepath=None, t_refs=None, uhi_maxs=None, t_raster_filepaths=None, station_t_filepath=None, station_locations_filepath=None, dates=None, workspace_dir=None, extra_ucm_args=None)¶

Initialize a Pythonic Urban Cooling Model wrapper.

Parameters:

lulc_raster_filepath (str) – Path to the raster of land use/land cover (LULC) file.
biophysical_table_filepath (str) – Path to the biophysical table CSV file.
cc_method (str) – Cooling capacity calculation method. Can be either ‘factors’ or ‘intensity’.
ref_et_raster_filepaths (str or list-like) – Path to the reference evapotranspiration raster, or sequence of strings with a path to the reference evapotranspiration raster.
aoi_vector_filepath (str, optional) – Path to the area of interest vector. If not provided, the bounds of the LULC raster will be used.
t_refs (numeric or list-like, optional) – Reference air temperature. If not provided, it will be set as the minimum observed temperature (raster or station measurements, for each respective date if calibrating for multiple dates).
uhi_maxs (numeric or list-like, optional) – Magnitude of the UHI effect. If not provided, it will be set as the difference between the maximum and minimum observed temperature (raster or station measurements, for each respective date if calibrating for multiple dates).
t_raster_filepaths (str or list-like, optional) – Path to the observed temperature raster, or sequence of strings with a path to the observed temperature rasters. Required if calibrating against temperature map(s).
station_t_filepath (str, optional) – Path to a table of air temperature measurements where each column corresponds to a monitoring station and each row to a datetime. Required if calibrating against station measurements. Ignored if providing t_raster_filepaths.
station_locations_filepath (str, optional) – Path to a table with the locations of each monitoring station, where the first column features the station labels (that match the columns of the table of air temperature measurements), and there are (at least) a column labelled ‘x’ and a column labelled ‘y’ that correspod to the locations of each station (in the same CRS as the other rasters). Required if calibrating against station measurements. Ignored if providing t_raster_filepaths.
dates (str or datetime-like or list-like, optional) – Date or list of dates that correspond to each of the observed temperature raster provided in t_raster_filepaths. Ignored if station_t_filepath is provided.
workspace_dir (str, optional) – Path to the folder where the model outputs will be written. If not provided, a temporary directory will be used.
Extra_ucm_args (dict-like, optional) – Other keyword arguments to be passed to the execute method of the urban cooling model.

get_model_perf_df(*, ucm_args=None, compare_random=None, num_runs=None)¶

Compute a model performance data frame.

Compare the performance of the calibrated model with randomly sampling temperature values from the \([T_{ref}, T_{ref} + UHI_{max}]\) range according to a uniform and normal distribution. Requires that the object has been instantiated with either t_raster_filepath or station_t_filepath.

Parameters:

ucm_args (dict-like, optional) – Custom keyword arguments to be passed to the execute method of the urban cooling model. The provided keys will override those set in the base_args attribute of this class (set up in the initialization method).
compare_random (bool, optional) – Whether the performance of the urban cooling model should be compared to randomly sampling (from the uniform and normal distribution). If not provided, the value set in settings.DEFAULT_MODEL_PERF_COMPARE_RANDOM will be used.
num_runs (int, optional) – Number of runs over which the results of randomly sampling (from both the uniform and normal distribution) will be averaged. If not provided, the value set in settings.DEFAULT_MODEL_PERF_NUM_RUNS will be used. Ignored if compare_random is False.

Returns:

model_perf_df – Predicted temperature data array aligned with the LULC raster.

Return type:

pd.DataFrame

get_sample_comparison_df(*, ucm_args=None)¶

Compute a comparison data frame of the observed and predicted values.

Each row corresponds to a sample (i.e., station measurement for a specific date). Requires that the object has been instantiated with either t_raster_filepath or station_t_filepath.

Parameters:: ucm_args (dict-like, optional) – Custom keyword arguments to be passed to the execute method of the urban cooling model. The provided keys will override those set in the base_args attribute of this class (set up in the initialization method).
Returns:: sample_comparison_df – Comparison data frame with columns for the sample date, station, observed and predicted values.
Return type:: pd.DataFrame

predict_t_arr(i, *, ucm_args=None)¶

Predict a temperature array for one of the calibration dates.

Parameters:

i (int) – Positional index of the calibration date.
ucm_args (dict-like, optional) – Custom keyword arguments to be passed to the execute method of the urban cooling model. The provided keys will override those set in the base_args attribute of this class (set up in the initialization method).

Returns:

t_arr – Predicted temperature array aligned with the LULC raster for the selected date.

Return type:

np.ndarray

predict_t_da(*, ucm_args=None)¶

Predict a temperature data-array.

The array is aligned with the LULC raster for all the calibration dates.

Parameters:: ucm_args (dict-like, optional) – Custom keyword arguments to be passed to the execute method of the urban cooling model. The provided keys will override those set in the base_args attribute of this class (set up in the initialization method).
Returns:: t_da – Predicted temperature data array aligned with the LULC raster.
Return type:: xr.DataArray

The UCMCalibrator class inherits the Annealer from the simanneal package and makes use of the UCMWrapper class in order to apply the simulated annealing procedure to the InVEST urban cooling model.

class invest_ucm_calibration.UCMCalibrator(lulc_raster_filepath, biophysical_table_filepath, cc_method, ref_et_raster_filepaths, *, aoi_vector_filepath=None, t_refs=None, uhi_maxs=None, t_raster_filepaths=None, station_t_filepath=None, station_locations_filepath=None, dates=None, workspace_dir=None, initial_solution=None, extra_ucm_args=None, metric=None, stepsize=None, exclude_zero_kernel_dist=None, num_steps=None, num_update_logs=None)¶

Urban cooling model calibrator.

__init__(lulc_raster_filepath, biophysical_table_filepath, cc_method, ref_et_raster_filepaths, *, aoi_vector_filepath=None, t_refs=None, uhi_maxs=None, t_raster_filepaths=None, station_t_filepath=None, station_locations_filepath=None, dates=None, workspace_dir=None, initial_solution=None, extra_ucm_args=None, metric=None, stepsize=None, exclude_zero_kernel_dist=None, num_steps=None, num_update_logs=None)¶

Initialize the urban cooling model calibrator.

Parameters:

lulc_raster_filepath (str) – Path to the raster of land use/land cover (LULC) file.
biophysical_table_filepath (str) – Path to the biophysical table CSV file.
cc_method (str) – Cooling capacity calculation method. Can be either ‘factors’ or ‘intensity’.
ref_et_raster_filepaths (str or list-like) – Path to the reference evapotranspiration raster, or sequence of strings with a path to the reference evapotranspiration raster.
aoi_vector_filepath (str, optional) – Path to the area of interest vector. If not provided, the bounds of the LULC raster will be used.
t_refs (numeric or list-like, optional) – Reference air temperature. If not provided, it will be set as the minimum observed temperature (raster or station measurements, for each respective date if calibrating for multiple dates).
uhi_maxs (numeric or list-like, optional) – Magnitude of the UHI effect. If not provided, it will be set as the difference between the maximum and minimum observed temperature (raster or station measurements, for each respective date if calibrating for multiple dates).
t_raster_filepaths (str or list-like, optional) – Path to the observed temperature raster, or sequence of strings with a path to the observed temperature rasters. Required if calibrating against temperature map(s).
station_t_filepath (str, optional) – Path to a table of air temperature measurements where each column corresponds to a monitoring station and each row to a datetime. Required if calibrating against station measurements.
station_locations_filepath (str, optional) – Path to a table with the locations of each monitoring station, where the first column features the station labels (that match the columns of the table of air temperature measurements), and there are (at least) a column labelled ‘x’ and a column labelled ‘y’ that correspod to the locations of each station (in the same CRS as the other rasters). Required if calibrating against station measurements.
dates (str or datetime-like or list-like, optional) – Date or list of dates that correspond to each of the observed temperature raster provided in t_raster_filepaths. Ignored if station_t_filepath is provided.
workspace_dir (str, optional) – Path to the folder where the model outputs will be written. If not provided, a temporary directory will be used.
initial_solution (list-like, optional) – Sequence with the parameter values used as initial solution, of the form (t_air_average_radius, green_area_cooling_distance, cc_weight_shade, cc_weight_albedo, cc_weight_eti). If not provided, the default values of the urban cooling model will be used.
extra_ucm_args (dict-like, optional) – Other keyword arguments to be passed to the execute method of the urban cooling model.
metric ({'R2', 'MAE', 'RMSE'}, optional) – Target metric to optimize in the calibration. Can be either ‘R2’ for the R squared (which will be maximized), ‘MAE’ for the mean absolute error (which will be minimized) or ‘RMSE’ for the (root) mean squared error (which will be minimized). If not provided, the value set in settings.DEFAULT_METRIC will be used.
stepsize (numeric, optional) – Step size in terms of the fraction of each parameter when looking to select a neighbor solution for the following iteration. The neighbor will be randomly drawn from an uniform distribution in the [param - stepsize * param, param + stepsize * param] range. For example, with a step size of 0.3 and a ‘t_air_average_radius’ of 500 at a given iteration, the solution for the next iteration will be uniformly sampled from the [350, 650] range. If not provided, it will be taken from settings.DEFAULT_STEPSIZE.
exclude_zero_kernel_dist (bool, optional.) – Whether the calibration should consider parameters that lead to decay functions with a kernel distance of zero pixels (i.e., t_air_average_radius or green_area_cooling_distance lower than half the LULC pixel resolution). If not provided, the value set in settings.DEFAULT_EXCLUDE_ZERO_KERNEL_DIST will be used.
num_steps (int, optional.) – Number of iterations of the simulated annealing procedure. If not provided, the value set in settings.DEFAULT_NUM_STEPS will be used.
num_update_logs (int, default 100) – Number of updates that will be logged. If num_steps is equal to num_update_logs, each iteration will be logged. If not provided, the value set in settings.DEFAULT_UPDATE_LOGS will be used.

calibrate(*, initial_solution=None, num_steps=None, num_update_logs=None)¶

Calibrate the urban cooling model for the given data.

Run a simulated annealing procedure to get the arguments of the InVEST urban cooling model that minimize the performance metric.

Parameters:

initial_solution (list-like, optional) – Sequence with the parameter values used as initial solution, of the form (t_air_average_radius, green_area_cooling_distance, cc_weight_shade, cc_weight_albedo, cc_weight_eti) when the cooling capacity method is “factors”, or (t_air_average_radius, green_area_cooling_distance) when the method is “intensity”. If not provided, the default values of the urban cooling model will be used.
num_steps (int, optional.) – Number of iterations of the simulated annealing procedure. If not provided, the value set in settings.DEFAULT_NUM_STEPS will be used.
num_update_logs (int, default 100) – Number of updates that will be logged. If num_steps is equal to num_update_logs, each iteration will be logged. If not provided, the value set in settings.DEFAULT_UPDATE_LOGS will be used.

Returns:

(state, metric) – corresponding metric.

Return type:

the best state, i.e., combination of model parameters and the

get_model_perf_df(*, ucm_args=None, num_runs=None)¶

Compute a model performance data frame.

Compare the performance of the calibrated model with randomly sampling temperature values from the \([T_{ref}, T_{ref} + UHI_{max}]\) range according to a uniform and normal distribution. Requires that the object has been instantiated with either t_raster_filepath or station_t_filepath.

Parameters:

ucm_args (dict-like, optional) – Custom keyword arguments to be passed to the execute method of the urban cooling model. The provided keys will override those set in the current solution found by the calibrator, i.e., the state attribute.
num_runs (int, optional) – Number of runs over which the results of randomly sampling (from both the uniform and normal distribution) will be averaged. If not provided, the value set in settings.DEFAULT_MODEL_PERF_NUM_RUNS will be used.

Returns:

model_perf_df – Predicted temperature data array aligned with the LULC raster.

Return type:

pd.DataFrame

get_sample_comparison_df(*, ucm_args=None)¶

Compute a comparison data frame of the observed and predicted values.

Each row corresponds to a sample (i.e., station measurement for a specific date). Requires that the object has been instantiated with either t_raster_filepath or station_t_filepath.

Parameters:: ucm_args (dict-like, optional) – Custom keyword arguments to be passed to the execute method of the urban cooling model. The provided keys will override those set in the current solution found by the calibrator, i.e., the state attribute.
Returns:: sample_comparison_df – Comparison data frame with columns for the sample date, station, observed and predicted values.
Return type:: pd.DataFrame

predict_t_arr(i, *, ucm_args=None)¶

Predict a temperature array for one of the calibration dates.

Parameters:

i (int) – Positional index of the calibration date.
ucm_args (dict-like, optional) – Custom keyword arguments to be passed to the execute method of the urban cooling model. The provided keys will override those set in the base_args attribute of this class (set up in the initialization method).

Returns:

t_arr – Predicted temperature array aligned with the LULC raster for the selected date.

Return type:

np.ndarray

predict_t_da(*, ucm_args=None)¶

Predict a temperature data-array.

The array is aligned with the LULC raster for all the calibration dates.

Parameters:: ucm_args (dict-like, optional) – Custom keyword arguments to be passed to the execute method of the urban cooling model. The provided keys will override those set in the current solution found by the calibrator, i.e., the state attribute.
Returns:: t_da – Predicted temperature data array aligned with the LULC raster.
Return type:: xr.DataArray