Command-line interface (CLI)

invest_ucm_calibration.cli.main.cli(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=True, num_steps=None, num_update_logs=None, dst_filepath=None)

Calibrate the InVEST urban cooling model.

Parameters:

  • lulc_raster_filepath (str) – Path to the land use/land cover raster.

  • biophysical_table_filepath (str) – Path to the biophysical table.

  • cc_method (str) – Calibration method. Must be one of “factors” or “intensity”.

  • ref_et_raster_filepaths (str) – Path to the reference evapotranspiration raster, or sequence of paths to evapotranspiration rasters. If providing a sequence of paths, they must be enclosed by quotes and separated by either a comma or a space character (in the latter case, the file paths must not contain spaces).

  • 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 str, optional) – Reference air temperature or sequence of reference air temperatures. If providing a sequence of values, they must be enclosed by quotes and separated by either a comma or a space character. 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 str, optional) – Magnitude of the UHI effect or sequence of UHI effect magnitudes. 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, optional) – Path to the observed temperature raster, or sequence of strings of path to the observed temperature rasters. If providing a sequence of paths, they must be enclosed by quotes and separated by either a comma or a space character (in the latter case, the file paths must not contain spaces). Required if calibrating against temperature rasters. If not provided, station_t_filepath and station_locations_filepath must be provided.

  • 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 alongside station_locations_filepath if calibrating against station measurements. Otherwise, t_raster_filepaths must be provided.

  • 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 alongside station_t_filepath if calibrating against station measurements. Otherwise, t_raster_filepaths must be provided.

  • dates (str, 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 (str, optional) – Sequence with the parameter values used as initial solution, which can either be of the form (t_air_average_radius, green_area_cooling_distance, cc_weight_shade, cc_weight_albedo, cc_weight_eti) when cc_method is “factors”, or (t_air_average_radius, green_area_cooling_distance) when cc_method is “intensity”. If not provided, the default values of the urban cooling model will be used.

  • extra_ucm_args (str, optional) – Other keyword arguments to be passed to the execute method of the urban cooling model, as a sequence of “key:value” pairs, enclosed by quotes and separated by either a comma or a space character.

  • metric (str, 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, the value set in settings.DEFAULT_STEPSIZE will be used.

  • 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).

  • 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, optional) – 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.

  • dst_filepath (str, optional) – Path to dump the calibrated parameters. If not provided, no file will be created (nonetheless, the calibrated parameters will be logged).