Shapefile area averaging example

[cpelley]

Reviewing example

[cpelley]

https://github.com/dkillick/iris_example_code/blob/master/area_weights.ipynb#L18

I wouldn't go into detail of which iris Cube methods in the introduction. I think the introduction should just be short and sweet about what were about to help the user achieve.

By performing an area weighting it allows us to account for data cells that only fall partially within our geometry, by determining the percentage of the cell's area that falls within the geometry. We can use that percentage to define its overall contribution when we perform a mathematical operation on the values within the geometry (for example by using a function from iris.analysis that may be used in conjunction with cube.collapsed).

I would simply this to:
Area weighting allows us to account for data cells that only fall partially within our geometry, by determining the percentage of the cell's area that falls within this geometry.

Might it be worth adding a very brief sentence in the intro to explain what a shapefile is? If I were instructed to make use of shapefiles by my group and found this example, it might give me the right footing if it were explained to me what shapefiles are and common sources of where they come from (and very common situation for using them).

... actually reading on, you have given example usage!

[cpelley]

https://github.com/dkillick/iris_example_code/blob/master/area_weights.ipynb#L34

In the image the black grid is the grid of data cells from the cube, the blue line is the extent of the shapefile geometry and the green filled area is the area of the grid that sits within the shapefile.

There is only one grid in the image, simply say 'In the image, the cubes cells represented as a grid is shown, where the blue line...'

As in the image above, not all cells will be fully contained within the geometry but if we want to find only the rain that falls within the county's geometry then we need to find the area-weighted amount of the total rainfall for that cell that fell within the geometry.

I would change to:
As in the image above, not all cells will be fully contained within the geometry and so in order to determine the amount of rainfall within the county's geometry, we need to find the area-weighted amount of total rainfall for that cell that fell within the geometry.

[cpelley]

https://github.com/dkillick/iris_example_code/blob/master/area_weights.ipynb#L50

In this example we will determine the area-weighted average air temperature of the UK in the year 2098 in the A1B climate futures scenario.

To:
'...in the year 2098 for our A1B climate future scenario.'

OR:
'for one of our climate future scenarios (A1B).'

[cpelley]

https://github.com/dkillick/iris_example_code/blob/master/area_weights.ipynb#L120

The iris.analysis function that we will use to calculate the area weights require each lateral coordinate from the cube to have bounds set, so if either of our cube's lateral coordinates are not bounded, we use the guess_bounds method to set some bounds on each lateral coordinate.

The iris.analysis function that we will use to calculate the area weights... -> Calculating the geometry weights will require known bounds to our grid cells so if either of our cube's lateral coordinates are not bounded, we use the guess_bounds method to set assume appripriate bounds on each lateral coordinate.
require -> requires

[cpelley]

https://github.com/dkillick/iris_example_code/blob/master/area_weights.ipynb#L122

being -> specifically

[cpelley]

https://github.com/dkillick/iris_example_code/blob/master/area_weights.ipynb#L150

Here the shapefile is specified and read using functions built into cartopy.io. The UK's geometry is determined by iterating over all records contained within the shapefile, choosing that where attribute name_long matches ''United Kingdom'. These attributes are specific to each source's own shapefile conventions.

(you mention these attribute keys depending on the shapefile, but I think it would be good to emphasise that it not due to what vector data the shapefile contains, but what attributes whoever wrote it chose to describe this data)

This Natural Earth shapefile data was chosen here merely for simplicity's sake, but any shapefile can be loaded and accessed using the methods demonstrated here. It is worth noting that shpreader.natural_earth() returns a known filepath to the Cartopy default save location for the specific Natural Earth data requested. You could simply supply this location yourself.

A very similar process should be able to be followed with any standard shapefile, as all shapefiles should be loaded with both geometries() and records() methods #.1.. The geometries method will return a generator object of each geometry within the shapefile, while the records method will return a generator object of each record within the shapefile.

#.1. where the former returns a generator of geometries, while the later returns a generator of records.

[cpelley]

https://github.com/dkillick/iris_example_code/blob/master/area_weights.ipynb#L166

[5] is duplicated within [6]

[cpelley]

https://github.com/dkillick/iris_example_code/blob/master/area_weights.ipynb#L258

'in an' -> within the

Note, however, that the keys within an attributes dictionary are subject to change, and that code that expects a certain key to appear in an attributes dictionary may fail if the key is changed unexpectedly.

[cpelley]

https://github.com/dkillick/iris_example_code/blob/master/area_weights.ipynb#L295

..to find the mean, area weighted,

change to:
area weight mean

[cpelley]

https://github.com/dkillick/iris_example_code/blob/master/area_weights.ipynb#L304

end on -> end

[cpelley]

Might be useful to show printing the cube with 0, 10, 50, 100% weights acceptance (i.e. use the calculated weights to determine a mask). Gives a good visual image of the concept for them.

[cpelley]

References to http://scitools.org.uk/cartopy/docs/latest/tutorials/using_the_shapereader.html?

[cpelley]

Is the image you have an actual plot or just representative?

[DPeterK]

@cpelley Review actions... actioned!

[cpelley]

Thanks @dkillick

[cpelley]

@dkillick I don't see a commit with any changes which would reflect the discussion above. I have created a PR to reflect the changes I would suggest.

[DPeterK]

@cpelley that would be because I had to leave before I could commit the changes! I will do that and then probably close your PR...