Add nourishment functions

[wrightky]

PR introduces three main feature additions:

• nourishment_area: Adds two functions for the computation and plotting of the "nourishment area" of a seed injection point, i.e. the region of the domain which receives material from the injection point. Following the convention set by the exposure_time functions, this includes: (A) particle_track.nourishment_area(), which loops through a walk_data, and returns a raster indicating how many occasions each cell was occupied by particles, normalized to the range 0-1. Because these paths are single realizations and inherently spatially-noisey, this function also allows you to smooth the output with a gaussian filter controlled by the variable sigma. (B) routines.show_nourishment_area(), which provides an easy aesthetically-pleasing way to plot that output overtop one of the existing grids. The visit frequency raster is shown as a heatmap, in which alphas fade to zero near the tail of the colormap, indicating areas sparsely visited by particles. Users can control most of the features of the plot using the function inputs, which I've tested on WLD and DeltaRCM outputs and looks pretty spiffy in both applications. Examples shown below

• nourishment_time: Similarly adds two functions for the computation and plotting of the "nourishment time" of a seed injection point, i.e. the amount of time particles tend to spend in each area of the domain. In a way, this function is the time-equivalent of the above function: once particles get to a cell, how long on average do they stay there? Similarly broken up into computation (particle_track.nourishment_time()) and plotting (routines.show_nourishment_time()), with both functions working very similarly to above. Furthermore, if you take the product of the nourishment_time and nourishment_area output rasters, you obtain the same thing as if you just added up all of the time particles spent in each cell, which may be interesting in its own right. Example below

• Native boundary-cropping for unstruct2grid: Adds an optional parameter, boundary, to this function, which will optionally crop the interpolated rasters to a domain boundary using matplotlib.path.Path(). Previously, if your domain wasn't a perfect rectangle, areas outside would still get interpolated to a numeric value, so this just allows people to fix that boundary behavior.

I think the nourishment functions would make for a good new example, which I'd be happy to add to this PR before it's merged, if you agree that would be a worthwhile addition. If not, we can merge whenever things look good.

[wrightky]

Alright, I think this is ready for another look when you have a chance. In the latest commits, I have:

• Added a new example using the nourishment_area and nourishment_time functions, including docs, which also updates the DeltaRCM example data to have discharge
• Added unit tests for the nourishment_area and nourishment_time functions, as well as one for the new unstruct2grid boundary setting
• Fixed the error in unstruct2grid that was failing the unit tests
• Added an additional crop option to unstruct2grid, which can eliminate the all-nan border created when a boundary is specified, resulting in smaller output rasters
• Moved the scipy imports in particle_track into the preamble for unstruct2grid, as it was the only function using that package and should help reduce the overhead when we call on run_iteration
• Adopted a new algorithm for get_time_state which is cleaner, and should solve whatever weird issue was happening before.
• Incremented the version number

On that last point, that seems to be the only line with commits that conflict with the existing commits. Could use some help figuring out how to resolve that, still not very familiar with handling parallel commit histories.

[elbeejay]

On that last point, that seems to be the only line with commits that conflict with the existing commits. Could use some help figuring out how to resolve that, still not very familiar with handling parallel commit histories.

Sorry I missed addressing this point. GitHub has a reasonable conflict resolution built into the website, so I think you can do it in the PR by hitting the "Resolve conflicts" button and working through the GitHub GUI. Especially since the conflict is pretty minor.

Otherwise the other option (I'm familiar with) would be doing it via the command line by fetching the "current" version of the code and pulling it into your branch. Then the git CLI will prompt you to resolve the conflict there (which would only be the single line in that case as well).

Let me know if you want more info or want to go through it together and we can do that sometime.

[wrightky]

• Does the nourishment area image need a colorbar? I don't mind either way but was just a thought.

I think probably not, since everything is normalized. Included one for the time function because the nominal values mean something, whereas area is all relative.

• Add tests that use the smoothing in the nourishment calculations (sigma > 0)

Aside from being exhaustive, do you think there's any utility in doing this? When sigma > 0, it isn't easy to compute what the a priori answer should be without just using this function to compute it, so we'd essentially be forcing this function to give us the answer it already gave us.

• test_nourishment_area() fails when I run the unit tests locally (seems to be producing some nan values in place of some expected 0s?)

This was a good catch, fixed the assert to handle floats or nan

• Do we know if get_time_state() is working as intended? Doesn't have to be resolved by this PR if there is an issue but we should open up an issue if there is a known bug

All my local testing of the new version works, there's very little that can go wrong now that we've collapsed the main loops/ifs into one simple numpy search. But I still don't know if this is what was giving Nelson problems

[elbeejay]

• Does the nourishment area image need a colorbar? I don't mind either way but was just a thought.

I think probably not, since everything is normalized. Included one for the time function because the nominal values mean something, whereas area is all relative.

:+1:

• Add tests that use the smoothing in the nourishment calculations (sigma > 0)

Aside from being exhaustive, do you think there's any utility in doing this? When sigma > 0, it isn't easy to compute what the a priori answer should be without just using this function to compute it, so we'd essentially be forcing this function to give us the answer it already gave us.

I think it is worth doing (beyond being exhaustive) for the following 2 reasons:

1. Avoids any possibility of an errant typo or line-change accidentally disrupting the function or performance of that section of the code that slips by our visual check of a future PR
2. Will throw an error if one of the functions from an upstream library (scipy.ndimage.gaussian_filter in this case) is changed in a way that breaks this functionality or alters the output; whether that is changing the number or order of expected inputs/outputs or altering the function internals and the subsequent output. Then we'd have a chance to do any/all of the following: 1) pin the scipy version to one that works; 2) update the function to reflect the new scipy syntax; 3) if the result of the function call changes we could add a warning in our code to let users know their result might change depending on the version of scipy they have (admittedly for this function this is unlikely).

• test_nourishment_area() fails when I run the unit tests locally (seems to be producing some nan values in place of some expected 0s?)

This was a good catch, fixed the assert to handle floats or nan

:+1:

• Do we know if get_time_state() is working as intended? Doesn't have to be resolved by this PR if there is an issue but we should open up an issue if there is a known bug

All my local testing of the new version works, there's very little that can go wrong now that we've collapsed the main loops/ifs into one simple numpy search. But I still don't know if this is what was giving Nelson problems

Sounds good.

[wrightky]

Think this might be ready!