Add island buffering notebook

[mirahshi]

Adding a notebook demonstrating methods to create buffer zones around islands. Can be used to create refinement regions independently of elevation, e.g. for cases when the topography surrounding the island is varying.

[mandli]

@rjleveque thoughts?

[rjleveque]

Fantastic, thanks @mirahshi for putting this together!

This is nicely done and explains things well, with good examples.

A few suggestions:

1. We don't have a good standard way of noting the authors of notebooks, but we should give credit. (Note to @mandli: this is something we should perhaps discuss and standardize in a separate thread.) For now, I think it would be good to add a cell like:

    ### Version
    Written by: Your Name and github handle, date
    Runs with Clawpack v5.8.0

   similar to the Version cell that appears in some notebooks, like http://www.clawpack.org/gallery/_static/apps/notebooks/geoclaw/dtopotools_examples.html I suggest putting it under Version rather than adding a separate Author cell because I think in general notebooks may end up being revised or expanded by others in the future and then the Version cell could be updated to include other contributors.

2. You could also include something like the first paragraph of that notebook and then we will add it to the gallery.

3. To run the notebook I had to install scikit-image since that's not one of our standard dependencies. It might be good to note that in the introductory paragraph, with a link to https://scikit-image.org/docs/stable/install.html.

4. It might be good to document the buffer function a bit more, since this is the main tool that others might want to adapt to their own work. (And maybe we should incorporate it into topotools eventually.) In particular, say more about the required inputs (the shape of vertices, whether the polygon has to be convex, and how exactly scale is used). In the example you use scale=400 but I'm not sure what that means. The docstring says "expanded by a scalar factor" but it's not 400 times bigger, or even 400%.

5. It might be more natural to allow the user to specify a distance for buffering, e.g. we might want to buffer by some distance in meters on each side, or by a certain fraction of a degree.

6. Since a degree longitude is shorter than a degree latitude by cos(latitude), buffering by the same fraction of a degree in both directions wouldn't give equal distance, and conversely if you want to allow specifying a distance this different scaling has to be taken into account. I think the current scale factor is applied the same in latitude/longitude and so results in wider buffers (in meters) in the latitude direction?

[mandli]

That format for noting authors looks good to me. I am not sure what would be the best practice or where to look for another example either.

[mirahshi]

Thank you for the suggestions. I'll add in items 1-3 and include more details/documentation about the buffer function.

The current scale factor is applied the same to longitude and latitude, so in that case, the buffer would be wider in the latitude direction distance-wise. I'll look into buffering by distance and see how the conversions between longitude and latitude would work.

Thanks!

[mandli]

The Haversine formula is the easiest way to use distance based on a longitude-latitude.

[rjleveque]

Note that haversine is implemented in geoclaw.util

[mirahshi]

Added suggestions above. Users can now specify either a distance (in meters) or degree to buffer by.

[mandli]

Everything works for me! Thanks for making those changes @mirahshi

[rjleveque]

Thanks @mirahshi, looks great!

I have added it to the notebook gallery.