diff --git a/_toc.yml b/_toc.yml index 3243d0ab7..dabe1bef3 100644 --- a/_toc.yml +++ b/_toc.yml @@ -66,6 +66,8 @@ title: Marking up Dataset page with Schema.org & Bioschemas for SEO #FCB012 - file: content/recipes/findability/seo/bioschemas-datacatalog title: Marking up Data Catalogue page with Schema.org & Bioschemas for SEO #FCB013 + - file: content/recipes/findability/annotation-tess + title: Annotating training materials in ELIXIR TeSS with interoperable keywords/registry entries #FCB087 - file: content/recipes/accessibility title: Accessibility diff --git a/content/recipes/findability/annotation-tess.md b/content/recipes/findability/annotation-tess.md new file mode 100644 index 000000000..5ccad727a --- /dev/null +++ b/content/recipes/findability/annotation-tess.md @@ -0,0 +1,227 @@ +(fcb-help-recipe-template)= +# Annotating training materials in ELIXIR TeSS with interoperable keywords/registry entries + +--- + +````{panels_fairplus} +:identifier_text: FCB___ +:identifier_link: https://w3id.org/faircookbook/FCB___ +:difficulty_level: 2 +:recipe_type: background_information +:reading_time_minutes: 15 +:intended_audience: principal_investigator, data_manager, data_scientist, funder +:maturity_level: 0 +:maturity_indicator: 0 +:has_executable_code: nope +:recipe_name: Recipe Template +```` + + +## Main Objectives + +In the following sections, we will provide instructions on annotating training materials in ELIXIR TeSS + +--- + + +## Graphical Overview + +```{note} +use this section to provide a decision tree for the overall process described in the recipe +For more information about the syntax used to generate the diagram, please refer to the [following documentation](https://mermaid-js.github.io/mermaid/#/flowchart) +``` + + +```{warning} + +Do make sure to save the mermaid diagram in a separate file using the '.mmd' extension. This is +d for building the book as the images are generated by the build process. +All the images will be generated as png files. + +``` + +Then reference the figure using the Alan Turing Institute style as shown below: + + +```{figure} ./images/C-3PO_droid.png +--- +width: 200px +name: This is a Robot +alt: C-3PO_droid +--- +C-3PO_droid +``` + + +--- + + +## Requirements + +* knowledge requirement: + * Please familiarize yourself with the [ELIXIR Training Lesson about TeSS](https://elixir-europe-training.github.io/ELIXIR-TrP-TeSS/chapters/00_Preface/#introduction). + + +--- + +## FAIRification Objectives, Inputs and Outputs + +| Actions.Objectives.Tasks | Input | Output | +| :------------- | :------------- | :------------- | +| [annotation](http://edamontology.org/data_2018) | [Data](http://edamontology.org/data_0006) | [Data](http://edamontology.org/data_0006)| + +## Table of Data Standards + +Authors should list all the data standards, format specification, syntax and controlled terminologies used in the FAIRification process applied to the IMI project data. +Ideally, authors should mark up the information using either EDAM Ontology URI or FAIRsharing identifiers (which are DOIs). + +| Terminologies | +| :------------- | +| [FAIRsharing](https://doi.org/10.25504/FAIRsharing.2abjs5) | +|[EDAM](https://doi.org/10.25504/FAIRsharing.a6r7zs)| +|[bio.tools](https://doi.org/10.25504/FAIRsharing.63520c)| + +--- + +## Main Content + + + +### Annotating TeSS with FAIRsharing identifiers + +```{note} +Note that you need to be the resource creator of the page or have annotator privileges on TeSS to add these annotations on a previously generated pages +``` +Each FAIRsharing entry is assigned a human-readable, unique identifier. + +IMAGE + +These allow to trace resources and integrate FAIRsharing data with other resources. To annotate a TeSS entry with FAIRsharing identifiers, follow these steps: + +1. Please select event or material you wish to annotate on TeSS or create a new one. +1. Click the EDIT button on the top right. +1. In this edit mode, scroll down to the "Suggested policies, standards and databases to associate with this resource" section and expand it. +1. Type the name of the standard/repository/policy to be associated with the TeSS entry. You have the option to choose one of the sub-registries from FAIRsharing. +1. Click on the "+" symbol to add the identifier to the page. +1. Scroll to the bottom and click the orange "update" button to publish your updates. +1. The annotation will appear on the materials page in the External resources section + +This annotations can be used for filtered queries on TeSS using the syntax: + +```https://tess.elixir-europe.org/SUBREGISTRYstandard_database_or_policy=FAIRSHARING_NAME``` + +where SUBREGISTRY is one of the subregistries of TeSS (e.g. "materials") and FAIRSHARING_NAME is the name (not the DOI) associated with the FAIRsharing entry. In the case of training materials for the European Nucleotide Archive, for example, the query sting would be: + +```https://tess.elixir-europe.org/materials?standard_database_or_policy=European+Nucleotide+Archive``` + + +### Annotating TeSS with bio.tools identifiers + +Each bio.tools entry is assigned a human-readable, unique identifier. + +IMAGE HERE + +These identifiers provide a reference to a "Tool Cards" of essential information. These allow to trace resources and integrate bio.tools data with other resources. To annotate a TeSS entry with bio.tools identifiers, follow these steps: + +1. Please select event or material you wish to annotate on TeSS or create a new one. +1. Click the EDIT button on the top right. +1. In this edit mode, scroll down to the "Suggested tools to associate with this resource" section and expand it. +1. Type the name of the tool to be associated with the TeSS entry. +1. Click on the "+" symbol to add the identifier to the page. +1. Scroll to the bottom and click the orange "update" button to publish your updates. +1. The annotation will appear on the materials page in the External resources section + +### Annotating TeSS with EDAM ontology + +#### Annotating with EDAM main terms + +TeSS pages can be annotated using two subregistries of EDAM: "Scientific topics" and "Operations". These would need to be added separately. To annotate a TeSS entry using a main terms of EDAM, use the following procedure: + +1. Please select event or material you wish to annotate on TeSS or create a new one. +1. Click the EDIT button on the top right. +1. In this edit mode, scroll down to the "Scientific topics" or to the "Operations" section. +1. Type the name of the main EDAM term to be associated with the TeSS entry. As you are typing, suggestions will be provided. If no relevant suggestions appear, follow the block of [instructions below](). ADD LINK +1. Click on the suggestion to add the annotation to the page. +1. Scroll to the bottom and click the orange "update" button to publish your updates. +1. The annotation will appear on the materials page in the "Scientific Topics" and "Operations" sections. Note that the terms are not clickable. + + +#### Browse through synonyms on EDAM to find the right class + +In the current integration ([Version: 1.4.1](https://github.com/ElixirTeSS/TeSS/releases/tag/v1.4.1)), TeSS only displays the main EDAM terms. Synonyms cannot be accessed. Instructions on how to browse this additional information are provided below: + +1.Open the [NCBO BioPortal](https://bioportal.bioontology.org/) +1.Under "Find an ontology", start typing "EDAM" and click on "EDAM - The data analysis and management ontology" +1. Open the "Classes" tab and type your desired term. This will search also through synonyms and provide a better suggestion than the native TeSS implementation. +1. Use the "preferred name" as the main EDAM term when following the block of instructions above. + +Note that EDAM supports a wide range on synonyms with various degrees of semantic proximity to the main term. + +--- + +## Conclusion + +Summerize Key Learnings of the recipe. + +Suggest further reading using the following: +### What to read next? +* [Tips and Tricks](./tips-tricks.md) +* [how-to-create-recipe-with-hackmd](./how-to-create-recipe-with-hackmd.md) +* using a reference tag affored by MyST markdown and sphinx with JupyterBook 0.7+. + [my-prefered-label](fcb-help-recipe-template) + + + + + + +## Authors + +Diana Pilvar - review, editing +Gil Poiares-Oliveira - review, editing +Federico Bianchini - writing, conceptualization, original draft +Jeanne Wilbrandt - review +Helena Schnitzer- review +Daniel Wibberg - review + + +```{note} +List the recipe contributors following the structure below and using the CASRAI credit vocabulary and do not change the structure of the table. + - Conceptualization + - Data curation + - Formal Analysis + - Funding acquisition + - Investigation + - Methodology + - Project administration + + - Resources + - Software + - Supervision + - Validation + - Visualization + - Writing - original draft + - Writing - review & editing +``` + +```{admonition} Important +:class: tip +This section is relied upon by another component developed by FAIRplus to enhance search and presentation. It is therefore important to comply with the layout. +``` + +````{note} +Consult the python file [global_variables_fairplus.py](https://github.com/FAIRplus/the-fair-cookbook/blob/migrating/_ext/global_variables_fairplus.py) +```` + + +````{authors_fairplus} +Philippe: Writing - Review & Editing +Wei: Writing - Review & Editing +```` + + +## License +````{license_fairplus} +CC-BY-4.0 +```` +