natcap.invest.urban_mental_health.urban_mental_health

InVEST Urban Mental Health model.

natcap.invest.urban_mental_health.urban_mental_health.build_lulc_ndvi_table(lulc_df, target_output_csv, base_lulc_path, base_ndvi_path)

Write csv table showing ndvi by lulc class with exclude mapped to nodata

Parameters:

• lulc_df (DataFrame) – lulc attribute table dataframe

• target_output_csv (str) – path to output csv to save lulc:ndvi mapping

• base_lulc_path (str) – path to baseline LULC raster

• base_ndvi_path (str) – path to baseline NDVI raster

Returns:

None.

natcap.invest.urban_mental_health.urban_mental_health.calc_baseline_cases(population_raster, base_prevalence_vector, target_base_prevalence_raster, target_base_cases)

Calculate baseline cases via incidence_rate * population

Parameters:

• population_raster (str) – path to aligned population raster representing the number of inhabitants per pixel across the study area. Pixels with no population should be assigned a value of 0.

• base_prevalence_vector (str) – path to vector with field risk_rate that provides the baseline prevalence (or incidence) rate of a mental health outcome by spatial unit (e.g., census tract).

• target_base_prevalence_raster (str) – target output path for rasterized baseline prevalence

• target_base_cases (str) – target output path for baseline cases raster

Returns:

None.

natcap.invest.urban_mental_health.urban_mental_health.calc_preventable_cases(delta_ndvi, baseline_cases, effect_size, target_preventable_cases)

Calculate preventable cases

PC = PF * BC PF = 1 - RR RR=exp(ln(RR_0.1NE) * 10 * delta_NE)

PC = (1 - exp(ln(RR_0.1NE) * 10 * delta_NE))*BC

PC: preventable cases PF: preventable fraction BC: baseline cases RR: relative risk or risk ratio NE: nature exposure, as approximated by NDVI RR0.1NE: RR per 0.1 NE increase. Note: The model uses the relative risk associated with a 0.1 increase in NDVI-based nature exposure. This value is provided by users as the effect size value.

Parameters:

• delta_ndvi (str) – path to raster representing change in NDVI from baseline to alternate/counterfactual scenario

• baseline_cases (str) – path to raster of number of baseline cases

• effect_size (float) – health indicator-specific effect size, given as a risk ratio, representing the relationship between nature exposure and mental health outcomes.

• target_preventable_cases (str) – path to output preventable cases raster

Returns:

None.

natcap.invest.urban_mental_health.urban_mental_health.calc_preventable_cost(preventable_cases, health_cost_rate, target_preventable_cost)

Calculate preventable cost

Parameters:

• preventable_cases (str) – path to preventable cases raster

• health_cost_rate (float) – cost per case of the mental health outcome

• target_preventable_cost (str) – path to output preventable cost raster

Returns:

None.

natcap.invest.urban_mental_health.urban_mental_health.check_raster_against_aoi_bounds(aoi_bbox, aoi_sr, raster)

Check if raster bounds are >= bounds of AOI + search_radius.

Check if the bounds of the raster extend at least search_radius meters beyond the bounds of the AOI vector. Logs a warning if the raster extent is too small.

Parameters:

• aoi_bbox (list) – aoi bounds in format [xmin, ymin, xmax, ymax], calculated by extending the input vector AOI bounds by search_radius meters (in the case of NDVI or LULC rasters)

• aoi_sr (osr spatial reference) – The defined spatial reference of the AOI, which is the target spatial reference of the model

• raster (str) – path to raster

Returns:

None.

natcap.invest.urban_mental_health.urban_mental_health.execute(args)

Urban Mental Health.

The model estimates the impacts of nature exposure, and more specifically residential greenness, on mental health. Residential nature exposure is defined as the average NDVI within a distance of a residence that benefits human mental health. The mental health model calculates the preventable mental disorder cases at the pixel level, based on the selected urban greening scenario.

Parameters:

• args['workspace_dir'] (str) – (required) A path to the directory that will write output, intermediate, and other temporary files during calculation.

• args['results_suffix'] (str) – (optional) Appended to any output filename.

• args['aoi_path'] (str) – (required) Path to a polygon vector that is projected in a coordinate system with units of meters. The polygon should intersect the baseline prevalence vector and the population raster.

• args['population_raster'] (str) – (required) Path to a raster of gridded population data representing the number of people per pixel.

• args['search_radius'] (float) – (required) Distance used to define the surrounding area of a person’s residence that best represents daily exposure to nearby nature. Must be > 0.

• args['effect_size'] (float) – (required) Health indicator-specific effect size representing the relationship between nature exposure and the mental health outcome, given as relative risk associated with a 0.1 increase in NDVI.

• args['baseline_prevalence_vector'] (str) – (required) Path to a vector providing the baseline prevalence (or incidence) rate of a specific mental health outcome (e.g., depression or anxiety) across administrative units within the study area. This data allows the model to estimate preventable cases by comparing current rates with those projected under improved nature exposure scenarios. The vector must contain field risk_rate.

• args['health_cost_rate'] (float) – (optional) The societal cost per case (e.g., in USD PPP) for the mental health outcome described by the baseline_prevalence_vector. This data enables the model to estimate the economic value of preventable cases under different urban nature scenarios. Costs can be specified at national, regional, or local levels depending on data availability.

• args['model_option'] (str) – (required) Which of the two land use options to model.

• args['ndvi_base'] (str) – Required if args['model_option'] != 'lulc' or not args['lulc_attr_csv']. A path to a Normalized Difference Vegetation Index raster representing current or baseline conditions, which gives the greenness of vegetation in a given cell.

• args['ndvi_alt'] (str) – Required if args['model_option'] == 'ndvi'. A path to an NDVI raster under future or counterfactual conditions.

• args['lulc_base'] (str) – Required if args['model_option'] == 'lulc'. A path to a Land Use/Land Cover raster showing current or baseline conditions.

• args['lulc_alt'] (str) – Required if args['model_option'] == 'lulc'. A path to a Land Use/Land Cover raster showing a future or counterfactual scenario.

• args['lulc_attr_csv'] (str) –

  Required if (args['model_option'] == 'lulc' and not args['ndvi_base']) or (args[model_option] != 'lulc' and lulc_base). A path to a CSV table that maps LULC codes to corresponding NDVI values and specifies whether to exclude the LULC class from analysis. The table should contain the following fields:

  • lucode (int): (required) Unique LULC class identifier.

  • ndvi (float): Required if args['model_option'] == 'lulc'

    and not args['ndvi_base']. NDVI value of the LULC class.

  • exclude (bool): (required) Specifies whether to keep (0)

    or mask out (1) the LULC class.

Returns:

File registry dictionary mapping MODEL_SPEC output ids to absolute paths.

Return type:

dict

natcap.invest.urban_mental_health.urban_mental_health.mask_ndvi(input_ndvi, target_masked_ndvi, input_lulc, lulc_df, target_lulc_mask)

Mask NDVI using either threshold of NDVI<0 or LULC exclude codes

Parameters:

• input_ndvi (str) – path to NDVI raster

• target_masked_ndvi (str) – path to output masked NDVI raster

• input_lulc (str) – path to LULC raster or None if not provided by user

• lulc_df (DataFrame) – (required if input_lulc) lulc attribute table dataframe or None

• target_lulc_mask (str) – (required if input_lulc) path to output binary mask or None

Returns:

None.

natcap.invest.urban_mental_health.urban_mental_health.reclassify_lulc_raster(lulc, mean_ndvi_by_lulc_csv, target_path)

Reclassify LULC raster: Map mean NDVI values onto LULC.

Reclassify LULC raster using a precomputed mapping in mean_ndvi_by_lulc_csv. Note that this will set any lulc class with an associated exclude value of 1 (based on the lulc_attr_csv) to NODATA in the raster created.

Parameters:

• lulc (str) – path to LULC raster (base or alt)

• mean_ndvi_by_lulc_csv (path) – path to csv mapping lucodes to mean ndvi

• target_path (str) – path to output raster with NDVI values mapped onto LULC classes

Returns:

None.

natcap.invest.urban_mental_health.urban_mental_health.zonal_stats_preventable_cases_cost(base_vector_path, model_option, target_stats_csv, target_aggregate_vector_path, preventable_cases_raster, preventable_cost_raster=None)

Calculate zonal statistics for each polygon in the AOI.

Write results to a csv and vector file.

Parameters:

• base_vector_path (string) – path to the AOI vector.

• model_option (string) – either ‘ndvi’ or ‘lulc’, used to label output gpkg layer

• target_stats_csv (string) – path to csv file to store dictionary returned by zonal stats.

• target_aggregate_vector_path (string) – path to vector to store zonal stats

• preventable_cases_raster (string) – path to preventable cases raster, which gets aggregated by AOI polygon(s).

• preventable_cost_raster (string) – (optional) path to preventable cost raster, which gets aggregated by AOI polygon(s).

Returns:

None.