Implement Urban Mental Health Option 1: Tree Canopy Cover + NDVI Inputs by claire-simpson · Pull Request #2314 · natcap/invest

claire-simpson · 2026-01-24T00:01:34Z

Description

Implements Option 1 (tree canopy cover–based scenarios) for the Urban Mental Health model by translating a user-defined tree cover target into an NDVI-based nature exposure scenario (to create 'alternate NDVI').

This PR adds a population-weighted, non-linear translation between tree canopy cover (%) and NDVI exposure, following the framework described in the UMH design document.

The steps are as follows:

Align input rasters
Mask baseline NDVI (mask out water or other excluded LULC classes or mask by 0 threshold)
Compute neighborhood NDVI exposure by convolving masked NDVI using the search_radius
Compute neighborhood tree canopy cover (TCC) exposure by convolving TCC using the same search_radius
Extract exposure values block-wise: iterate over aligned blocks of buffer-mean NDVI exposure, buffer-mean TCC exposure, and population (masking no data values and pixels with no population)
Bin TCC values: assign each valid pixel to a TCC bin (range: [0, 100])
Compute population-weighted mean NDVI per bin
Fit a linear GAM using population per bin as weights (so bins w/ more people influence the fit more), to get a function mapping TCC exposure to NDVI exposure
Evaluate the fitted function at the user-specified tree cover target value to get the NDVI target
Generate the alternate NDVI exposure raster via: NDVI_alt = NDVI_base + (NDVI_target - f(TCC_pixel))
Compute change in nature exposure via NE_delta = NDVI_alt - NDVI_base
Mask out negative values in NE_delta

Notes:

Population is used only as a weighting factor, not as a spatial transform of TCC or NDVI.
Both NDVI and TCC are evaluated on the same neighborhood (buffer) scale, so:
- The GAM learns a relationship between experienced canopy cover and experienced greenness, not pixel-level vegetation
- Alternate NDVI is generated directly on the exposure scale, so no additional convolution is required after translation.
Tests are not complete (see Add/update tests for Urban Mental Health #2316), and I haven't added pygam as an InVEST dependency (see below)

Open Questions

Is the above workflow/math correct, specifically w.r.t (1) calculating mean within a buffer distance (i.e., 2d convolution operation) for both NDVI and TCC before fitting the GAM and translating TCC to alternate NDVI and (2) using the population to both compute a population-weighted conditional mean of NDVI for each TCC "bin" and as a weight when fitting the GAM (population is not explicitly used to create a population-weighted TCC layer)
Are we ok adding pygam as a dependency? There are definitely alternative options like using scipy.interpolate.UnivariateSpline. If so, I'd need to add pygam to requirements.txt.
Are we ok with the binning approach to reduce memory use? In a comment in the design doc, Yingjie clarified that their inputs to the GAM were aggregated at the tract level before fitting this model (to avoid loading the entire NDVI, TCC, and population rasters into memory). However in our implementation, we are not requiring users to input tracts (though we could!). There are certainly other alternative approaches we could take to fitting the TCC-NDVI relationship, including:

Random spatial sampling of NDVI and TCC rasters (within iterblocks)
Spatial window aggregation: iterate over fixed-sized windows and compute mean NDVI and TCC and fit GAM on window-level summaries (or just downsample both rasters to have fewer pixels)

Fixes #2141

Checklist

Updated HISTORY.rst and link to any relevant issue (if these changes are user-facing)
Updated the user's guide (if needed)
Tested the Workbench UI (if relevant)

…lation; better document fit and apply functions natcap#2141

…ix test natcap#2141

claire-simpson · 2026-01-29T00:33:45Z

tests/test_urban_mental_health.py

            numpy.testing.assert_allclose(
                actual_mean_ndvi[key], expected_mean_ndvi[key], atol=1e-6)
+
+    # def test_option1_tcc_input(self):


Template for test for whole model, but I commented it out because there is still uncertainty around population weighting and whether to convolve TCC before fitting GAM - see #2316

natcap#2141

claire-simpson · 2026-01-29T18:57:28Z

src/natcap/invest/urban_mental_health/urban_mental_health.py

+
+    curve_smooth = gam.predict(centers.reshape(-1, 1))
+
+    fig, ax = plt.subplots()


I believe matplotlib is a new dependency as of the reports PR so I assume this would be the first time a graph is created within a model. This was an intermediate output of the demo model and seems useful for interpreting the relationship between TCC and NDVI, so I think it'd be great to ultimately include in the report. However maybe saving this as a standalone isn't needed?

If it feels like a useful standalone output, I think it's fine to save on its own along with adding to the report if it'd be useful there too.

It might be worth thinking about whether we should be saving the numpy arrays for centers, curve, and others as intermediate outputs.

dcdenu4

Thanks @claire-simpson ! I don't have too many comments but think it'd be best to walk through the curve fitting part on a call, after we talk with Yingjie, or with Yingjie too!

dcdenu4 · 2026-02-03T15:36:52Z

src/natcap/invest/urban_mental_health/urban_mental_health.py

+import matplotlib.pyplot as plt
 import numpy
 import pandas
+from pygam import LinearGAM, s # Are we ok to add pygam as new invest dependency? Alternatively, could us scipy.UnivariateSpline


I'd be interesting in talking about how scipy.UnivariateSpline could be an alternative.

dcdenu4 · 2026-02-03T15:45:48Z

src/natcap/invest/urban_mental_health/urban_mental_health.py

    mental disorder cases at the pixel level, based on the selected urban
    greening scenario.

    Args:


Has this docstring been keeping pace with the MODEL_SPEC updates? In terms of descriptive text and required / optional flags.

dcdenu4 · 2026-02-03T16:01:59Z

src/natcap/invest/urban_mental_health/urban_mental_health.py

+    if args['scenario'] == 'tcc_ndvi':
+        LOGGER.info("Using Tree Canopy Cover and NDVI inputs")
+        mean_buffered_tcc_task = task_graph.add_task(
+            func=pygeoprocessing.convolve_2d,


Yep, I think using a dichotomous kernel and convolving with normalize_kernel=True gets you a mean value within the given kernel radius.

dcdenu4 · 2026-02-03T16:06:19Z

src/natcap/invest/urban_mental_health/urban_mental_health.py

+                  file_registry['tree_cover_buffer_mean'],
+                  args['tree_cover_target'],
+                  file_registry['ndvi_alt_buffer_mean'],
+                  file_registry['result_fig_tc_ndvi_plot']),


Should the plot output also be in the target_path_list below?

dcdenu4 · 2026-02-03T16:07:36Z

src/natcap/invest/urban_mental_health/urban_mental_health.py

+    Writes alt NDVI raster where each pixel's NDVI is increased based on
+    the difference between the target NDVI (based on tc_target) and the
+    NDVI predicted by the TC-->NDVI curve at that pixel's tree cover value.


Should we mention how population is used at all for weighting?

dcdenu4 · 2026-02-03T16:09:42Z

src/natcap/invest/urban_mental_health/urban_mental_health.py

+        population_path (str): path to population raster
+        tree_cover_path (str): path to tree cover raster with pixels in
+            range [0, 100]
+        tc_target (float): target tree canopy cover value (in range [0,100])


Suggested change

tc_target (float): target tree canopy cover value (in range [0,100])

tc_target (float): target tree canopy cover value as a percentage (in range [0,100])

dcdenu4 · 2026-02-03T16:15:17Z

src/natcap/invest/urban_mental_health/urban_mental_health.py

+        None
+    """
+
+    centers, curve = _fit_tc_to_ndvi_curve(


I'm wondering if this should be its own taskgraph step in the workflow instead of called in here? Benefits could be avoided re-computation, more modular step by step breakout in execute, and maybe more targeted testing?

dcdenu4 · 2026-02-03T16:15:39Z

src/natcap/invest/urban_mental_health/urban_mental_health.py

+    Args:
+        base_ndvi_path (str): path to baseline NDVI raster
+        tree_cover_path (str): path to tree cover raster
+        population_path (str): path to population raster


Density or count? For future us mostly.

dcdenu4 · 2026-02-03T16:27:18Z

src/natcap/invest/urban_mental_health/urban_mental_health.py

+
+    curve_smooth = gam.predict(centers.reshape(-1, 1))
+
+    fig, ax = plt.subplots()


If it feels like a useful standalone output, I think it's fine to save on its own along with adding to the report if it'd be useful there too.

It might be worth thinking about whether we should be saving the numpy arrays for centers, curve, and others as intermediate outputs.

dcdenu4 · 2026-02-03T16:38:29Z

src/natcap/invest/urban_mental_health/urban_mental_health.py

+                  file_registry['population_aligned'],
+                  file_registry['tree_cover_buffer_mean'],
+                  args['tree_cover_target'],
+                  file_registry['ndvi_alt_buffer_mean'],


Maybe its worth updating ndvi_alt_buffer_mean, since this function isn't really returning a buffered mean? Right?

claire-simpson added 4 commits January 15, 2026 15:38

Make subpackage for umh natcap#2141

2d4e3ab

Other changes related to subpackage move natcap#2141

c4b1e27

Implement option 1: TCC and NDVI inputs; reorganize logic natcap#2141

ded4c9b

Clarify model spec text and fix mask logic when pop<0 natcap#2141

1b53623

claire-simpson changed the base branch from main to feature/urban-health-model January 24, 2026 00:01

claire-simpson added 4 commits January 27, 2026 16:04

Add mean buffer calc for TCC; make a graph to check TCC to NDVI trans…

9ceb101

…lation; better document fit and apply functions natcap#2141

Add tests for TCC input option 1 natcap#2141

a7802ab

Add comments, fix nbins and nsplines defaults natcap#2141

d1fe0dc

Unify resample population raster function for all input options and f…

6e53d4f

…ix test natcap#2141

claire-simpson commented Jan 29, 2026

View reviewed changes

claire-simpson added 2 commits January 29, 2026 09:41

Fix test failure in test_diff_prj_inputs_opt1; clean up code natcap#2141

67e7515

Use bilinear resampling for tcc; fix task dependencies; better plotting

23d9ae3

natcap#2141

claire-simpson commented Jan 29, 2026

View reviewed changes

Remove todo comment natcap#2141

b8232ef

claire-simpson marked this pull request as ready for review January 29, 2026 19:06

claire-simpson requested review from dcdenu4 and emilyanndavis January 29, 2026 19:07

dcdenu4 requested changes Feb 3, 2026

View reviewed changes

claire-simpson added 2 commits February 13, 2026 13:24

Fix/simplify logic of tcc option when calculating delta_NDVI natcap#2141

eccc42e

Remove old option 1 apply gam function natcap#2141

29af18e

claire-simpson marked this pull request as draft February 18, 2026 23:41

claire-simpson added the on hold There's a reason we're not working on this yet label Feb 18, 2026

claire-simpson mentioned this pull request Feb 19, 2026

Implement final pieces of Urban Health Model #2391

Open


		curve_smooth = gam.predict(centers.reshape(-1, 1))

		fig, ax = plt.subplots()

	tc_target (float): target tree canopy cover value (in range [0,100])
	tc_target (float): target tree canopy cover value as a percentage (in range [0,100])

Conversation

claire-simpson commented Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dcdenu4 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

claire-simpson commented Jan 24, 2026 •

edited

Loading