Adding "supplements" property to research product versions

[lzehl]

@apdavison @bweyers @skoehnen @tgbugs @UlrikeS91 @jagru20 @olinux @MBAbrams @visakhmr @Peyman-N

I received a request to add a property to research product versions where links could be added to additional material / tutorials made for the particular research product version. For example a link to the INCF training space or a Collab.

What is you opinion? (feel also free to make suggestions for the property name)

[bweyers]

In general, this sounds quite nice. However, it would make sense to give this a little bit more semantics...

[lzehl]

@bweyers could you make suggestions?

Notes from Jan B. : 1) "Will these links be stable, or will training/supplementary material links be reorganized and moved around from time to time? If we are uncertain, it would have been preferred to make the user aware of the possibility to search for a training/supplementary information e.g. through INCF Training Space or other places." 2) "linking out to training for a particular tool would of course be relevant. But it might need to be explained and brought into context."

I think point 2 is related to @bweyers comment. Point 1 is valid, I'm not sure if we can guarantee that these links are stable. Question is if there is a way of handling this better than just pointing users to a place where they then have to search for the matching training material / supplements.

@apdavison @bweyers @skoehnen @tgbugs @UlrikeS91 @jagru20 @olinux @MBAbrams @visakhmr @Peyman-N Looking forward to your comments/ideas.

[UlrikeS91]

Point 1 is valid, I'm not sure if we can guarantee that these links are stable. Question is if there is a way of handling this better than just pointing users to a place where they then have to search for the matching training material / supplements.

It's generally tricky to ensure stabel links for anything that is not maintained by us directly (and even those aren't quite stable either sometimes...). This is of course part of what the curators do, but it would be nice to have as few of these as possible. I can't really come up with a good solution on how to ensure stable links, but I think point 2/@bweyers comment could help with that.

2. "linking out to training for a particular tool would of course be relevant. But it might need to be explained and brought into context."

Some additional information next to the link could ensure that users can find the supplementary information/resource regardless. Maybe:

• name: aka title of the supplementary information/resource
• host: similar to FileRepository, especially if we add "platform" next to "organization" as options
• IRI or URL and/or a DigitalIdentifier?: link to the supplementary information/resource
• resourceType: controlledTerm to capture what that supplementary information/resource is, e.g. "training video", "instruction manual", "tutorial" or similar

On the other hand, if we were to create an additional schema for such supplementary information/resources, we may need to consider to pull properties like "RelatedPublication", "FullDocumentation" and even "homepage" potentially in there as well. I know this is a pretty drastic view point, but all of these properties allow either URL and/or a DigitalIdentifier. URL especially will require a lot of maintenance...

[lzehl]

this discussion is still ongoing... but it will be a backwards compatible change so it should not block us for the next release.

[heplesser]

One specific use-case for "supplements" would be to manage tutorial material for EBRAINS tools and services. The key distinction between documentation and tutorials is that for documentation, we typically have a one-to-one mapping from a tool or service to its canonical main documentation page, while there will often be a one-to-many mapping from tools to tutorials. Key metadata for tutorials from my point would be

• Author(s)
• Title
• Short description
• Level: beginner/intermediate/expert
• Link to tutorial

I am not sure about the best way to establish links between tools/services/workflows and tutorials. Probably the links should go both ways, but they need to be consistent (symmetric) and stay so when changes are made. And one always wants to avoid duplicity—I'll leave that to the experts.

Concerning link stability: Could one implement regular automated checks for all links stored in KG and then flag broken ones as stale and potentially as something to be followed up by curators?

[lzehl]

"""Concerning link stability: Could one implement regular automated checks for all links stored in KG and then flag broken ones as stale and potentially as something to be followed up by curators?"""

Link stability was also Jan Bjaalies major concern. @olinux if I remember correctly you suggested exactly what @heplesser is asking correct?

[lzehl]

I see that this issue will not only talk about linking various supplements via URLs in a property "supplements", but it moves towards having the property "supplements" linking to various supplment specific schemas (e.g., tutorials, presentations, posters, etc). If that is the case @apdavison could you comment in how far this would overlap with the openMINDS publication extension?

[lzehl]

@heplesser thanks for your comment. This helps a lot pushing this issue forward

[apdavison]

@lzehl the publication extension currently covers live papers plus traditional articles, book chapters, monographs, but it could easily be extended to other formats (blog posts, posters, videos, tutorials).

[lzehl]

@apdavison I thought as much. I think this would be a great opportunity to link the publication extension to the other metadata models.

[jagru20]

I quickly want to ask, how this woul exactly look like, we just got another request to add tutorials and demos to a software. Are there any advances on this?

[MBAbrams]

@jagru20 TrainingSpace is available for you to add your tutorials and demos. The Virtual Brain is currently doing this with the tutorials linked from the EBRAINS website to TrainingSpace (https://ebrains.eu/service/the-virtual-brain#simulate_tvb_multiscale). If you are interested, let me know.

[lzehl]

@jagru20 for a concrete schema for integrating this into openMINDS we did not further discuss yet. Not sure if @apdavison already made some extensions to openMINDS_publication ?

[lzehl]

@MBAbrams should we have a closer look at the TrainingSpace schemas in this context? I mean regarding their compatibility with openMINDS (or actually the other way around)...

[MBAbrams]

@lzehl Yes, we should have a discussion about this. I will also bring in Pradeep.

[apdavison]

I've quickly put together a possible schema plus controlled terms to address at least part of this ticket, aiming principally to cover tutorials, but as @UlrikeS91 points out above, this could also be used to replace the "fullDocumentation" property.

• https://github.com/HumanBrainProject/openMINDS_publications/pull/2
• https://github.com/HumanBrainProject/openMINDS_controlledTerms/pull/350

The schema is based on https://schema.org/LearningResource. I didn't know where to find the TrainingSpace schemas, so feedback from @MBAbrams would be welcome.

@heplesser what do you think?

[lzehl]

@apdavison thanks for putting something together. I've only had a few comments in the PRs for clarifications.

For the "fullDocumentation" I think this is not equivalent to a training resource. Training resources do not necessarily provide a (full or partial) documentation of the RPV. They focus on a certain usage or application of the (complete or partial) data presented in the RPV. I would definitely keep those in separate properties. I also think @UlrikeS91 comment was originally aimed at the point that "externalResources" would indeed cover all (documentation, training, publications). I think it makes sense if we capture each of them separately.

[heplesser]

@apdavison This looks very promising, but I must admit that I have no experience with creating metadata schema, so I can only comment based on initial observations. What I have seen so far looks decent to me, but I think it would be helpful to create a few worked-out examples to see how it works in practice. I assume you are in contact with the HLST doc team (Anne Devismes, Jessica Mitchell) about this? They might not yet have access to this repo.