CF Section 7.5 Geometries coordinates/grid_mapping attribute "carried by" clarification

[benjwadams]

Question

I am attempting to create a check for CF section 7.5 Geometries and need some clarification on the following paragraph:

A geometry container variable acts as a container for attributes that describe a set of geometries. The geometry attribute of the data variable contains the name of a geometry container variable. The geometry container variable must hold geometry_type and node_coordinates attributes. The grid_mapping and coordinates attributes can be carried by the geometry container variable provided they are also carried by the data variables associated with the container.

Emphasis mine. What does "carried by" mean here? For example, can you have data variables with a polar coordinates attribute and a geometry given in cartesian coordinates, or do both have to match if present in both the data variables and referred geometry container variable?

[JonathanGregory]

Dear @benjwadams

Thanks for the question. The text should be clearer! I believe that "carried by" means "attributes of" in that sentence. That is, the geometry container variable may (optionally) have a coordinates attribute and a grid_mapping attribute, but if it does, the data variable must also have such attributes, and they must be consistent between the geometry containing and data variables. They have to "match", as you say. I suppose they don't have to be identical, because the container variable coordinates and grid_mapping attributes would only name relevant coordinates and grid mappings, I guess. Does that make sense?

Best wishes

Jonathan

[benjwadams]

They have to "match", as you say. I suppose they don't have to be identical, because the container variable coordinates and grid_m, can gpping attributes would only name relevant coordinates and grid mappings, I guess

Could you supply an example of a non-identical case where both the geometry container variable and parent attributes are defined? I.e. for coordinates for geometry variables x y be a subset of the parent variable x y z?

I should be able to link to some unit test code briefly to ensure I have the proper implementation.

[benjwadams]

https://github.com/ioos/compliance-checker/blob/5eff67fda7e9575b8433640e3154c7fd204f1b06/compliance_checker/tests/test_cf.py#L2879-L2889

Basically checks if parent variable is defined with mismatched (as in string inequality) coordinates and/or grid_mapping values vs the geometry container variable.

[JonathanGregory]

Example 7.16 (in Sect 7.5) is a case where the coordinates attribute is attached to both the data variable and the geometry container variable, but they are not identical, although they are consistent. These are the relevant lines:

  float geometry_container ;
    geometry_container:coordinates = "lat lon" ;
  double someData(instance, time) ;
    someData:coordinates = "time lat lon" ;

This isn't an ideal example, because time(time) is a coordinate variable (not an auxiliary coordinate variable). Therefore it's unnecessary to include it in the coordinates attribute of the data variable, although it's allowed to do so. Another way in which they could be consistent but not identical is simply to be in a different order e.g. geometry_container:coordinates = "lat lon" and someData:coordinates = "lon lat".

The document doesn't have an example of the grid_mapping attributes being different yet consistent. I haven't used this kind of the data myself. Therefore I'm not sure this is right, but I think it would be like this, where I've combined parts of Examples 7.16 and 5.10:

dimensions:
  node = 12 ;
  instance = 2 ;
  part = 4 ;
  time = 4 ;
  height = 10 ;
variables:
  int time(time) ;
    time:units = "days since 2000-01-01" ;
  float height(height);
    height:units = "m";
    height:standard_name = "height";
    height:long_name = "distance above the surface";
    height:positive = "up";
    height:axis = "Z";
  int model_level(height);
    model_level:standard_name = "model_level_number";
    model_level:units = "1";
  double x(node) ;
    x:axis = "X" ;
    x:standard_name = "projection_x_coordinate" ;
    x:units = "m" ;
  double y(node) ;
    y:axis = "Y" ;
    y:standard_name = "projection_y_coordinate" ;
    y:units = "m" ;
  double northing(instance) ;
    northing:nodes = "y" ;
    northing:standard_name = "projection_y_coordinate" ;
    northing:units = "m" ;
  double easting(instance) ;
    easting:nodes = "x" ;
    easting:standard_name = "projection_x_coordinate" ;
    easting:units = "m" ;
  double lat(instance) ;
    lat:units = "degrees_north" ;
    lat:standard_name = "latitude" ;
  double lon(instance) ;
    lon:units = "degrees_east" ;
    lon:standard_name = "longitude" ;
  float geometry_container ;
    geometry_container:geometry_type = "polygon" ;
    geometry_container:node_count = "node_count" ;
    geometry_container:node_coordinates = "x y" ;
    geometry_container:grid_mapping = "crsOSGB" ;
    geometry_container:coordinates = "northing easting" ;
    geometry_container:part_node_count = "part_node_count" ;
    geometry_container:interior_ring = "interior_ring" ;
  int node_count(instance) ;
  int part_node_count(part) ;
  int interior_ring(part) ;
  float datum ;
    datum:grid_mapping_name = "latitude_longitude" ;
    datum:semi_major_axis = 6378137. ;
    datum:inverse_flattening = 298.257223563 ;
    datum:longitude_of_prime_meridian = 0. ;
  int crsOSGB ;
    crsOSGB:grid_mapping_name = "transverse_mercator";
    crsOSGB:semi_major_axis = 6377563.396 ;
    crsOSGB:inverse_flattening = 299.3249646 ;
    crsOSGB:longitude_of_prime_meridian = 0.0 ;
    crsOSGB:latitude_of_projection_origin = 49.0 ;
    crsOSGB:longitude_of_central_meridian = -2.0 ;
    crsOSGB:scale_factor_at_central_meridian = 0.9996012717 ;
    crsOSGB:false_easting = 400000.0 ;
    crsOSGB:false_northing = -100000.0 ;
    crsOSGB:unit = "metre" ;
  double someData(height, instance, time) ;
    someData:coordinates = "model_level lat lon easting northing" ;
    someData:grid_mapping = "crsOSGB: easting northing datum: lat lon" ;
    someData:geometry = "geometry_container" ;

In this conflated example, someData:coordinates = "model_level lat lon easting northing" identifies all the auxiliary coordinate variables of the data variable. Each data value has been located both in latitude and longitude using the datum grid mapping, and in eastings and northings using the crsOGB grid mapping (the UK national grid). Therefore the data variable's grid_mapping attribute mentions both grid mapping variables, indicating which auxiliary coordinate variables apply to each.

Since the node coordinates are given in the crsOGB grid mapping, the datum grid mapping and the lat and lon variables are not relevant to the geometry container variable. Hence its coordinates and grid_mapping variables do not mention those ones.

Does anyone else have real use-cases for a situation like this, which combines grid mapping and simple geometries? Do you have any among your example datasets, Luke @lhmarsden and Ag @agstephens, for instance? Could you comment on whether my example is correct, Dave @dblodgett-usgs?

[lhmarsden]

@JonathanGregory I think your example looks okay.

Does anyone else have real use-cases for a situation like this, which combines grid mapping and simple geometries?

I know of examples where people have encoded data like this. Though I am not sure they would be helpful in this case. They are someone's interpretation of CF, which could be a correct or incorrect interpretation.

More complicated queries like this make me realise that it is very important that we have a catalogue of peer-reviewed example datasets, probably using synthetic rather than real-world examples. Much work ahead!

[JonathanGregory]

Thanks for having a look, Luke @lhmarsden. I agree that a collection of examples will be very valuable for many purposes. It has often been requested in past years too, so thanks for taking an interest in it.