Adding figure to paragraph "Bounds for 2-D coordinate variables with 4-sided cells" in Section 7.1 on bounds

[neumannd]

Title: Adding figure to paragraph "Bounds for 2-D coordinate variables with 4-sided cells" in Section 7.1 on bounds
Moderator: @erget
Requirement Summary: It would be nice to have a visual representation of the paragraph following "Bounds for 2-D coordinate variables with 4-sided cells" (in Section 7.1), which helps users to quickly grasp what is meant. Particularly a user might look for the order in which the four coordinates of the four vertices of a grid cell should be written into the bounds variable.
Technical Proposal Summary: Add a figure that visualizes the textual description and particulary shows the order of the vertices in the bounds variable.
Benefits: A user who looks for the particular information described in the Requirement Summary get this information considerably faster.
Status Quo: Currently, a textual description is provided. It is well written and the reader (who knows for what he/she is looking) understands what is meant. However, it takes some time. Additionally, some readers, who have difficulties imagining the spatial structure, will have issues understanding what is meant.
Detailed Proposal: Add a figure as described above. I will be happy to provide a draft figure next week if there is positive feedback.

[davidhassell]

I am happy, in general, for figures to be used in the conventions document as a supplement to the text, rather than a replacement for text.

So I support this.

[neumannd]

Attached two suggestions for the described figures. The grid lines are drawn in red and the grid cell center in green. Maybe I should add a legend?

I generated the figures with R.

[JimBiardCics]

The figures look great. One thing though. The color choice is problematic for some color-blind people. If they suffer from red-blind protanopia, the image looks like

A different color scheme might be advisable.

[davidhassell]

These are very good diagrams - thanks.

Some thoughts:

The axis labels in the second figure are not quite right - the axes are not longitude and latitude. I think you can be completely general and use discrete axes, i.e. just increasing in index (i, j) space; or else give an example of associated strictly monotonic 1-d coordinates: grid_longitude, grid_latitude or projection_x_coordinate, projection_y_coordinate. I might favour the former, more general, approach, as it more matches the text in 7.1 better, but I don't have a strong opinion.

The conventions numbers vertices 0, 1, 2, 3, so the diagrams should match this.

In the first diagram (1-d case), a legend mentioning that the trailing index numbers are reversed when the coordinates are decreasing would be useful, perhaps.

Thanks,
David

[neumannd]

@JimBiardCics Thanks for the remark. I will update the colors.

@davidhassell Thanks for the remarks.

The conventions numbers vertices 0, 1, 2, 3, so the diagrams should match this.

I will update it.

In the first diagram (1-d case), a legend mentioning that the trailing index numbers are reversed when the coordinates are decreasing would be useful, perhaps.

Or should I just duplicate the first diagram and create one with decreasing lon/x-axis to the right?

The axis labels in the second figure are not quite right - the axes are not longitude and latitude. I think you can be completely general and use discrete axes, i.e. just increasing in index (i, j) space; or [...]

I don't under that remark correctly. The i and j indices are not increasing along the axes. At least it is not meant to be this way. Therefore, it would not be correct to replace the longitude by i index and latitude by j index. I will create another figure and show what I mean.

[neumannd]

updates:

• updated colors (took colors from the beginning and end of the viridis color scale).
• updated indices of bnds (0-based instead of 1-based)
• legend added to 1D case
• added to more grid cell centers to 2D plot to indicate index order

[neumannd]

The source for the pictures is available via a GitHub repository:

https://github.com/neumannd/cell_bounds_figures_for_cf_conventions

[neumannd]

Are the figures OK how they are? Is it feasible to include them into CF-1.8?

push

[neumannd]

Unfortunately, we did not assign a moderator here so that this issue was forgotten. Are there any caveats including these figures into the CF conventions?

[JonathanGregory]

I see no reason in principle against diagrams in the document. On the contrary, they would be an enhancement. I think the question is technical: can they be included in AsciiDoc, and will the software which builds the HTML and the PDF from the AsciiDoc be able to process them properly?

[taylor13]

I'm either confused, or I agree with @davidhassell (#193 (comment)) that in the lower figure the abscissa and ordinate axes are mislabeled. Don't the dashed lines in the figure represent lines of latitude and longitude, not the horizontal and vertical axes? I would think that the horizontal axis would simply be i (or some function of i alone).

[neumannd]

@taylor13

Maybe this figures shows clearer what I mean?

lon1, lon2, ... actually mean lon_bnd1, lon_bnds2, ... .

For my example I assume that we have some grid, which is not orientated along the lon and lat axis. The grid is somehow curved. I tried to include an i-axis into the plot from above (i_{n-1}, i_{n}, i_{n+1} are the i-values):

I could draw the i and j indices into a plot with regular i and j axes. However, we could not reasonably include the lon-lat-information there. It would look like this:

[taylor13]

I was indeed confused, but I probably shouldn't have been. Thanks for going to the trouble of explaining. I think your original diagram should be clear enough to those thinking clearly.

[neumannd]

@taylor13 : Thanks for the feedback. If it is clearer on the first view, I could adapt the original figure to be like the first figure in my last comment -- printing (lon_bnds_n, lat_bnds_n)-tuples at the vertices and writing lon_bnds_n = lon_bnds(i, j, n), ... at the top.

[davidhassell]

Hello @neumannd,

It'd be very useful if you briefly summarize this issue https://docs.google.com/document/d/1urPWngzDCuHTrfpA8nedGoRDVKXs5OmjqO8M6i3UZJM/edit#, including what might be good outcomes from a discussion at the CF meeting. If this could be done today or tomorrow that would be best, as we will use it to help people decide on which sessions to attend in advance of the meeting.

Many thanks,
David

[davidhassell]

Hello,

The timings and order of the breakout groups for the CF meeting next week has now been set (see http://cfconventions.org/Meetings/2020-Workshop.html), and the discussion of this issue will be on Wednesday 10 June from 17:30-19:00 UTC, in parallel with three other topics.

Thanks.

[neumannd]

@davidhassell Thanks. Noted in my calender. Thanks for preparing the documentation.

[erget]

@neumannd my apologies that this fell by the wayside - as we discussed at the CF Community Meeting I, too, support this proposal and am happy to moderate so that we can get this into 1.9. I'll add a summary shortly.

[erget]

This issue is already quite mature. In summary:

• A figure was proposed in order to improve the clarity of the Conventions document
• This has been improved based on feedback from multiple reviewers
• The figure as it stands is considered to add value to the document
• The only thing that is missing is a pull request that inserts the figures into the text of the document.

@neumannd would you be so kind as to create a PR showing where this would go into the document? As we already have sufficient voices expressing favour and no concerns, I will start the first 3-week period directly once the PR stands, so that barring dissent the proposal can be merged in 6 weeks from the PR's creation.

[neumannd]

Discussed in a break out group at the CF Conventions Annual Meeting 2020. Short minutes are provided here in a Google Doc.

Summary:

• visualization corresponding to the text
• faster unterstanding of the order of vertex coordinates
• colors taken from viridis color palette => colorblind viewers of different types can distinguish the different colors
• no comments on needed changes
• pull request due to submit (just done)

[erget]

The proposed changes to the text are minimal, essentially adding only the 2 diagrams and some explanatory text. I invite all who are interested to review the changes in the Pull Request (e.g. by downloading the PDF build artefact) and raise concerns, should there be any.

I will check in on this on 1 Jul 2020, with a sunny day plan of merging this on 22 Jul 2020.

[erget]

This proposal has remained unchanged for 3 weeks and no objections have been raised. That means that it is stable and if no objections are raised I will merge the corresponding pull request on 2020-07-22.

[neumannd]

@erget Thanks