Roles best practice

[cholmes]

Related Issue(s): #966

Proposed Changes:

1. Added best practice section on asset roles
2. Made a list of common roles in best practice, borrowing many from card4l
3. Moved visual and overview roles out to be in the best practice, as they aren't actually used that much today.

PR Checklist:

• This PR is made against the dev branch (all proposed changes except releases should be against dev, not master).
• This PR has no breaking changes.
• I have added my changes to the CHANGELOG

[cholmes]

Still some more to do here, like adding a bit more on the common roles and when / how to use them. But I think it's mostly done, any review is appreciated. As well as other 'role' ideas, I think a long list makes sense.

[philvarner]

Maybe also mention their use in Extensions -- for example, we use (proprietarily) a role of labels on assets in Items using the Label Extension, and there's discussion of changing that spec to use this role instead of requiring the asset be named 'labels'

[cholmes]

Sounds good. Will add labels to the list, and mention extensions.

[cholmes]

Actually I don't think I'll add this yet, since right now it's not actually specified in the label extension. When #1001 is complete we can add it (or it can add it to this list if we merge this one first).

[m-mohr]

Also applies to links?!

[cholmes]

It does, but that whole section is really focused on asset media types. I can rename the title to 'working with asset media types'. Or could move it, but not sure where - I'm mostly looking for the best way to 'group' things to help people navigate a bit. Links cuts across all of them...

[emmanuelmathot]

related to the SAR, I would the following specific roles:

amplitude (GRD)
magnitude (SLC)
coherence
phase
sigma0
gamma0
beta0
displacement

[matthewhanson]

I like most of the roles added in the new list, but rather than include some really specific and little used SAR roles, what about just including those with the SAR extension as recommended roles?

There might be other roles tied to specific extensions, but SAR always seems to be the main source of lots of extra complicating fields.
I'd like to see the SAR specific ones removed and added to the SAR extension along with @emmanuelmathot's suggestions.

[matthewhanson]

Mentioned in mtg the other day, but a common asset among scientific geospatial data are plots or other graphics. These might indicate a fit of a curve to generate the main derived products, QC summary info, or ancillary info about applied corrections.

Would graphic be a good name for this?

[m-mohr]

related to the SAR, I would the following specific roles:

And that's why it's a bad idea to copy/past just from CARD4L: Some entries only make sense in combination with the CARD4L spec. What is meant with sigma-gamma was the sigma-gamma ratio and not a specific sigma or gamma asset.
Do we actually need roles for those files? Isn't it better to have a SAR field for the values above and then use data? How often are these really combined so that roles make sense?

[m-mohr]

I like most of the roles added in the new list, but rather than include some really specific and little used SAR roles, what about just including those with the SAR extension as recommended roles?

But then I'm wondering why not add all the cloud related stuff also to the EO extension etc? cloud_cover is also in eo and thus listing the roles there makes more sense to me. In best practices just list the domain agnostic roles (there are not many of them).

[m-mohr]

Would graphic be a good name for this?

Is this an asset or a link? I think in CARD4L we somehow imply to use a link with rel type related...

[emmanuelmathot]

Do we actually need roles for those files? Isn't it better to have a SAR field for the values above and then use data? How often are these really combined so that roles make sense?

Ok but then the rationale should also apply for optical data. For instance, reflectance should be part of the eo extension. if the roles field "are used to describe what each asset is used for.", then being exhaustive to be sure we share common terms to describe the same measurements is not useless.

[cholmes]

I like most of the roles added in the new list, but rather than include some really specific and little used SAR roles, what about just including those with the SAR extension as recommended roles?

But then I'm wondering why not add all the cloud related stuff also to the EO extension etc?

Sure, that makes sense to me. I think my only small hesitation is that these are at the level of 'best practice', not 'standard', and in the extension feels a bit more standard. But I think we have talked about a 'best practices' section in extensions, so I can just use this to start those. Would want to link from the overall best practice to the eo and sar roles sections, but that seems reasonable.

[matthewhanson]

This makes sense to me too (to put most of these in EO/SAR extension).

So with that I would say keep the roles here as the most generic ones:
thumbnail
overview
date
graphic - supporting plot, illustration, or graph associated with the Item

Plus data and metadata which are in the item-spec but didn't make it here (I think anything in item-spec should be included here)

Maybe saturation ?
I can also include including general masks here: snow-ice, land-water, mask

For the others:

EO Extension
reflectance
temperature
cloud
cloud-shadow

View Extension
azimuth
sun-azimuth
sun-elevation
terrain-shadow
terrain-occlusion
terrain-illumination

SAR Extension
contributing-area
local-incidence-angle
noise-power
gamma-sigma
date-offset
backscatter
covmat
prd

[m-mohr]

gamma-sigma

Please note that this has been renamed in CARD4L for clarity reasons to gamma-sigma-ratio

Saturation could also start in eo, I think.

I'm not overly happy with "mask", even in CARD4L. Maybe we should rename that to something else? Ideas for improvements?

[matthewhanson]

I agree mask is too generic, what does it represent in CARD4L, nodata?

nodata-mask would be good for the general Best Practices

[m-mohr]

regarding mask:

It's from the SAR spec and includes

• Valid data
• Invalid data
• No-data

Optionally:

• Layover (included as invalid data in Threshold)
• Radar shadow (included as invalid data in Threshold)
• Ocean water, etc.

[matthewhanson]

Differentiating between Invalid and Nodata doesn't seem useful, IMHO, does CARD4L require a difference? Without it this would just be a nodata-mask

[emmanuelmathot]

Sorry for the late contribution. I added roles corresponding to the conventions used in SAR and covering previous roles. May be reviewed in the future.

[cholmes]

@emmanuelmathot - thanks! I didn't realize you'd be working so late, and checked to see if you had accepted the invite, so thought you were done for the day - would have waited for your to come in.

I think your commit missed my table of contents update, and unfortunately right now the SAR table needs to be updated in two places (included it in the SAR extension directly, but wanted a good list in one place in best practices). If you are able to clean those up that'd be great, but I can also probably do it later today.

[cholmes]

Oh great, I see you got in the SAR extension one as I was writing. thanks

[emmanuelmathot]

I merged your table of content change. didn't I? Sorry if I missed something.

[cholmes]

@emmanuelmathot - you did, but I took it out due to #989 (comment) Hrmm... I thought I reverted it, due to #1006 But now I can't find my reverting commit, so maybe I just thought I did. I'll figure it out.

[matthewhanson]

I think @m-mohr and I were thinking the same thing, that the generic Roles table wouldn't include extension specific Roles, such as the SAR related ones.

But I don't have a really strong opinion here so I'm going to get this approved.

[cholmes]

Ok, I think this is good to go. Final approval appreciated.

[m-mohr]

Looks good, but still fearing that the lists of roles get out of sync.

[cholmes]

I hear you, but I do think the value of being able to see all the potential roles in one place outweighs the downside if they get a little out of date.

[m-mohr]

@cholmes It will likely not be all roles in the future as extension development will be in separate repo for many, releases will be separate, new extensions will occur and stac spec will release much less often so basically this will always be an incomplete list. People should actually not understand it as a complete list. Give it a month or two after the release and I think it will be outdated and incomplete. Just saying...

[m-mohr]

I just saw the last commit. That's a good change!