Initial draft of specification

[bekozi]

I think we should move forward with the initial specification draft. @bekozi has a skeleton and example CDL for major geometry types. @twhiteaker has already added some text (for example).

I'm going to start working on filling in missing sections. Any contributions would be greatly appreciated. Let me know if you would like to work on a specific section.

The only piece not currently covered in the spec skeleton are parametric objects #8. Our ad hoc plan is to incorporate those within a spec tuned to the more common simple geometry types.

[twhiteaker]

I'm willing to help. I'm also causing trouble. See https://github.com/bekozi/netCDF-CF-simple-geometry/issues/26#issuecomment-235642477.

[dblodgett-usgs]

We should get the following summarized as some kind of diff of the current spec.

http://cfconventions.org/cf-conventions/cf-conventions.html#_features_and_feature_types

• [x] Add geometry to feature type table.
• [x] Modify language on timeSeries to indicate it can be points of geometries.
• [x] Update introduction about geometries to text below table 9.1

http://cfconventions.org/cf-conventions/cf-conventions.html#_collections_instances_and_elements

• [x] Describe how geometries relate to the instance and element dimensions.
• [x] Introduce the dimension(s) supporting multipart geometries.

http://cfconventions.org/cf-conventions/cf-conventions.html#representations-features

• [x] Describe our contiguous ragged array approach, how it is similar and how it is different from the sample dimension.
• [x] Add a 9.3.5 describing our contiguous ragged array approach.

http://cfconventions.org/cf-conventions/cf-conventions.html#featureType

• [ ] Add our approach to multiple featureType attributed variables per file.

http://cfconventions.org/cf-conventions/cf-conventions.html#coordinates-metadata

• [x] Add our approach to the use of cf_role
• [ ] Describe how we connect coordinates to coordinate_index(s) to variables.
• [ ] Generally edit concepts to clarify how they apply or don’t to geometry.

[dblodgett-usgs]

https://docs.google.com/document/d/1tpl2VL8Ed_or5BOffawKiaOitOaMuwWh6QzkI1BtCaA/edit Let's track changes here. I set it so anyone can comment / suggest edits will share with @bekozi and @twhiteaker as editors for now, let me know if others want edit rights.

[dblodgett-usgs]

Made a bit more progress... would be helpful to have another set of eyes on the doc.

[twhiteaker]

When I view the doc, I see your additions in red and deletions in red strikethrough, with comments describing everything that happened. How did you do that? When I delete something, it just disappears.

[dblodgett-usgs]

Looks like you figured it out? You can switch to from editing to suggesting in the upper right.

[twhiteaker]

Heh, nope. I just manually formatted with strikethrough and changed the color, and then added comments. I'll try to go back through and turn my edits into suggests.

[twhiteaker]

Did we decide on break value -1,-2 approach, or geom_part "g" "p" approach?

[dblodgett-usgs]

I think -1 ,-2. Would be good to highlight the benefits briefly.

[twhiteaker]

I introduced the dimension(s) supporting multipart geometries in 9.3.5.

I added a longer example to be placed in appendix H at the end. It needs a paragraph explaining the example.

[twhiteaker]

I cleaned up the H example. In that example, I describe how we connect coordinates to coordinate_index(s) to variables for the case of time series.

Multiple featureType attributed variables per file? Do we want to go there on the first cut? We might have more luck if we stay less controversial, leaving multiple featureType variables for a future more general CF DSG enhancement.

I've probably muddied up the doc enough that someone else should look at it for a while.

[dblodgett-usgs]

I made my way through the doc. This is looking pretty good. Thanks for all the contributions @twhiteaker. Maybe @bekozi could take a final whack at it and we can start to move it toward the CF list?

[dblodgett-usgs]

Comments from @bekozi relevant here from #50 comments.

I gave the DSG document an initial look through. This approach seems reasonable (editing the DSG spec as opposed to a new spec doc).

• I don't like how the point geometry is kept separate. Is this necessary to be compliant with DSG? The coordinate indexing is superfluous for points so it makes sense in that regard. It seems we should permit points to be stored in the newer geometry format as well.
• It is also not clear how the featureType attribute conundrum is resolved. Is DSG okay with a non-global feature type attribute? I didn't see where this attribute should go now that the global requirement is removed. I think it is on the data variables?
• Are we going exclusive with zero-based indexing only? I noticed that in the doc, but I thought we were supporting one-based as well. Zero is fine with me...just want to confirm.

[dblodgett-usgs]

I puttered around in the spec doc a bit more. Want to start accepting changes and look at a single clean 'dif' between the old and our suggestion.

• I got rid of point. I'm not sure anyone will really miss it.
• I attempted to resolve the featureType attribute, check it out and see what you think.
• Generally, I've cross referenced our old work on the wiki with what we have in there. Did we forget to add geom_dimension or are we dropping that?

[dblodgett-usgs]

@bekozi and @twhiteaker - I added a preface regarding how our work relates to OGC/ISO Simple Features. It aligns quite well since WKT is an implementation of simple features in essence.

Still waiting on further input on this stuff from you guys. I may come back a add some things, but mostly looking for you to edit / confirm what I've put together.

[twhiteaker]

I don't think we need the coordinate_index:geom_dimension attribute. You can infer that dimension from the coordinate_index_start variable, which has a contiguous_ragged_dimension attribute whose value is the dimension of the coordinate index variable. Right?

[twhiteaker]

@dblodgett-usgs I like the color coded tables you added. They illustrate the point nicely. I'm ok with what you did with featureType. We have a lot of attributes and related variables, but if you follow the breadcrumbs one attribute at a time, then it's clear which things are related.

Since you deleted point, I think you meant to put a comma between point and multipoint next to geometry in table 9.1 (so I did). There are a couple of other places where we'll need to add point as an acceptable value for geom_type (so I did) if we agree to drop point. I think you'll get some pushback from CF, as I think there are quite a few datasets already using DSG point, and using DSG point is simpler than our geometry:point. The benefit of dropping point is that there is a single geometry model for handling points instead of potentially two.

After @bekozi looks it over, I think it would be good to have someone not so close to our latest spec to have a look at it, to make sure it's understandable. @BobSimons would be good for this.

[twhiteaker]

I made some edits including to section 9.3.5 where all changes have previously been accepted. Have a look and accept if you agree.

I hope that leaving out required attributes cf_role and axis for the node variables in examples 9.1 and 9.2 doesn't confuse readers. Leaving those attributes out simplifies the examples to help with the learning curve, building up to example H.2.6 at the end.

[dblodgett-usgs]

I think we should leave everything that's required in the examples. I get that it would simplify things, but it could be confusing. Honestly, I could see removing the example CDL and referencing it in an appendix?

Another option would be to make the examples something other than well formed CDL so the tables make sense?

[dblodgett-usgs]

I moved cf_role and axis into the examples to make sure we are complete for now. Can change it later if people don't like it.