Addition of raster functionality

[kbonney]

Summary

This PR adds the function sample_raster to the wntr.gis module. The function samples a raster file at the coordinate points of the provided geodataframe (e.g., junctions from WaterNetworkGIS). This PR only extends the existing API and does not modify it (ie, the inclusion of the PR merits a minor version change at most).

Tests and documentation

One test is added to verify that the raster is correctly sampled. A docstring is included in the function definition. Currently no additional documentation is included, but there could be a subsection added to the Geospatial capabilities user manual page to discuss and exemplify usage of the new function.

Acknowledgement

By contributing to this software project, I acknowledge that I have reviewed the software quality assurance guidelines and that my contributions are submitted under the Revised BSD License.

[kbonney]

@dbhart, can you review this?

[dbhart]

@kbonney Looks good to me!

[kbonney]

Discussion points:

• Do we want users to pass in the raster object or the filepath? I opted to have the user pass in the filepath, so that the function can take care of opening and closing the file. If we have users pass in the raster directly, they may forget to close the connection to the file. Other geospatial capabilities directly ingest the geospatial data, rather than filepaths, but geodataframes are different because they exist in memory whereas the raster object is a connection to the file in storage.
• Do we want to include any raster plotting functionality? For example, the function might take an existing ax with something like a water network plotted on it, extract the extent, fetch the corresponding raster data within the extent, and plot it using imshow. Something like this might be nice for the saltwater demo.
• User manual docs?

[dbhart]

Note to all - failed tests due to actions runner issue that still needs to be merged into main

[kbonney]

Ok, thanks @dbhart. Any thoughts on the first discussion point above?

[dbhart]

i think that we pass the filename. if the file stays open rather than loading the raster into memory then i agree that we want control over opening and close the file

[coveralls]

coverage: 84.241% (+0.01%) from 84.227%
when pulling 807273a on kbonney:raster
into 576dc01 on USEPA:main.

[kbonney]

@kaklise,
Remade test to have verifiable sample values and to use Net1, also added the test as an example to the user docs.

[kaklise]

Looks good, just requesting minor updates to documentation