From cbd58931e807ef27a68ef67fb8c32b9b74909b27 Mon Sep 17 00:00:00 2001 From: Andres Tabima Date: Fri, 3 Jul 2026 11:24:16 +0200 Subject: [PATCH] Revert "Fair tutorial guidelines (#64)" This reverts commit 1762352205c7e4f0443e8eb3e1ed5c02da0090b2. --- .gitignore | 5 - CHANGELOG.md | 38 --- docs/commons/fair/fair-commons.rst | 1 - .../tutorials/create-test-following-ftr.rst | 88 ------ .../define-benchmark-associated-metrics.rst | 250 ------------------ .../define-run-scoring-algorithm.rst | 220 --------------- .../fair/tutorials/deploy-champion.rst | 47 ---- .../tutorials/find-metrics-and-benchmarks.rst | 239 ----------------- .../find-test-for-digital-object.rst | 250 ------------------ .../fair/tutorials/host-deploy-test.rst | 60 ----- .../commons/fair/tutorials/how-comply-ftr.rst | 158 ----------- .../fair/tutorials/register-benchmark.rst | 213 --------------- .../fair/tutorials/register-metric.rst | 229 ---------------- .../fair/tutorials/run-existing-test.rst | 31 --- .../commons/fair/tutorials/tutorial-index.rst | 23 -- docs/index.rst | 6 - .../ostrails-index.rst | 21 -- docs/tools/authoring.rst | 16 -- docs/tools/dmp.rst | 13 +- docs/tools/fair-assessment.rst | 18 -- docs/tools/fair.rst | 17 +- .../fair-assessment-authoring-tool.rst | 0 .../{assessment => fair}/fair-champion.rst | 0 .../fair-validator.rst | 0 docs/tools/{assessment => fair}/fairos.rst | 3 - .../fairassist.rst => fair/fairsharing.rst} | 0 docs/tools/{assessment => fair}/foops.rst | 0 docs/tools/{assessment => fair}/rsfc.rst | 0 docs/tools/quality-control.rst | 13 - docs/tools/toolbox.rst | 42 --- docs/tools/toolbox/dmp-metrics.rst | 8 - docs/tools/toolbox/dmp-tests.rst | 8 - docs/tools/toolbox/fair-algorithms.rst | 138 ---------- docs/tools/toolbox/fair-benchmarks.rst | 10 - docs/tools/toolbox/fair-metrics.rst | 8 - docs/tools/toolbox/fair-tests.rst | 139 ---------- 36 files changed, 11 insertions(+), 2301 deletions(-) delete mode 100644 CHANGELOG.md delete mode 100644 docs/commons/fair/tutorials/create-test-following-ftr.rst delete mode 100644 docs/commons/fair/tutorials/define-benchmark-associated-metrics.rst delete mode 100644 docs/commons/fair/tutorials/define-run-scoring-algorithm.rst delete mode 100644 docs/commons/fair/tutorials/deploy-champion.rst delete mode 100644 docs/commons/fair/tutorials/find-metrics-and-benchmarks.rst delete mode 100644 docs/commons/fair/tutorials/find-test-for-digital-object.rst delete mode 100644 docs/commons/fair/tutorials/host-deploy-test.rst delete mode 100644 docs/commons/fair/tutorials/how-comply-ftr.rst delete mode 100644 docs/commons/fair/tutorials/register-benchmark.rst delete mode 100644 docs/commons/fair/tutorials/register-metric.rst delete mode 100644 docs/commons/fair/tutorials/run-existing-test.rst delete mode 100644 docs/commons/fair/tutorials/tutorial-index.rst delete mode 100644 docs/tools/authoring-and-registering/ostrails-index.rst delete mode 100644 docs/tools/authoring.rst delete mode 100644 docs/tools/fair-assessment.rst rename docs/tools/{authoring-and-registering => fair}/fair-assessment-authoring-tool.rst (100%) rename docs/tools/{assessment => fair}/fair-champion.rst (100%) rename docs/tools/{quality-control => fair}/fair-validator.rst (100%) rename docs/tools/{assessment => fair}/fairos.rst (97%) rename docs/tools/{authoring-and-registering/fairassist.rst => fair/fairsharing.rst} (100%) rename docs/tools/{assessment => fair}/foops.rst (100%) rename docs/tools/{assessment => fair}/rsfc.rst (100%) delete mode 100644 docs/tools/quality-control.rst delete mode 100644 docs/tools/toolbox.rst delete mode 100644 docs/tools/toolbox/dmp-metrics.rst delete mode 100644 docs/tools/toolbox/dmp-tests.rst delete mode 100644 docs/tools/toolbox/fair-algorithms.rst delete mode 100644 docs/tools/toolbox/fair-benchmarks.rst delete mode 100644 docs/tools/toolbox/fair-metrics.rst delete mode 100644 docs/tools/toolbox/fair-tests.rst diff --git a/.gitignore b/.gitignore index 9a42903..b39712e 100644 --- a/.gitignore +++ b/.gitignore @@ -3,11 +3,6 @@ __pycache__/ *.py[cod] *$py.class -#AI Remnants -HANDOFF.md -handoff.md -Handoff.md - # C extensions *.so diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 7dae071..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,38 +0,0 @@ -# Changelog - -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## 2026-06-30 - -### Added -- `docs/tools/toolbox/fair-algorithms.rst`: new page documenting the FAIR Algorithms artefact type. -- `docs/tools/toolbox/fair-benchmarks.rst`: new page documenting the FAIR Benchmarks artefact type. -- `docs/tools/authoring-and-registering/ostrails-index.rst`: OSTrails index page for the authoring-and-registering section. -- `docs/tools/authoring.rst`: top-level section page for authoring tools. -- `docs/tools/fair-assessment.rst`: top-level section page for FAIR assessment tools. -- `docs/tools/quality-control.rst`: top-level section page for quality-control tools. - -### Changed -- Restructured the `docs/tools/` hierarchy: assessment tools (`fair-champion.rst`, `fairos.rst`, `foops.rst`, `rsfc.rst`) moved from `fair/` into `assessment/`; `fair-validator.rst` moved into `quality-control/`; authoring tools consolidated under `authoring-and-registering/`. -- `docs/tools/toolbox.rst`: updated to reflect the new deliverable-centric structure. -- `docs/index.rst`: updated top-level navigation to match the new hierarchy. - -### Removed -- `docs/tools/toolbox/testing-platforms.rst`: content superseded by the new section pages. - -## 2026-06-29 - -### Added -- Live FAIR test catalogue in `docs/tools/toolbox/fair-tests.rst`: fetches all tests from the OSTrails Champion API (`https://tools.ostrails.eu/champion/tests/`), renders each as a collapsible card showing title, description, identifier, endpoint, and OpenAPI link, with a filter-as-you-type search box. - -### Changed -- Toolbox section (`docs/tools/toolbox.rst`): updated title to "OSTrails DELIVERABLE 3.2: Toolbox of Testing Services"; revised introductory prose to clearly distinguish conceptual artefacts (Metrics, Benchmarks) from code-level artefacts (Tests, Algorithms) and explain the difference between DMP tests (code only) and FAIR tests (live endpoints). -- `docs/tools/toolbox/fair-metrics.rst`, `dmp-metrics.rst`, `dmp-tests.rst`: converted RST hyperlinks to raw HTML `` tags so links open in a new tab. - -## 2025-01-25 - -### Added -- Initial OSTrails documentation structure. diff --git a/docs/commons/fair/fair-commons.rst b/docs/commons/fair/fair-commons.rst index 2de2ce8..c5e03f7 100644 --- a/docs/commons/fair/fair-commons.rst +++ b/docs/commons/fair/fair-commons.rst @@ -20,5 +20,4 @@ The following resources in this section are part of the FAIR Commons component. Catalogue of Tests Catalogue of Benchmark Scoring Algorithms Code of Shared Tests - Tutorials diff --git a/docs/commons/fair/tutorials/create-test-following-ftr.rst b/docs/commons/fair/tutorials/create-test-following-ftr.rst deleted file mode 100644 index ecbfcc5..0000000 --- a/docs/commons/fair/tutorials/create-test-following-ftr.rst +++ /dev/null @@ -1,88 +0,0 @@ -.. _tutorial_create_metric_tests: - -How to Create and Register a Test following the FTR API -======================================================= - -Benchmark Assessment Algorithms rely on **FAIR Metric Tests**. - -Each test evaluates a specific FAIR requirement and returns a result of: - -* ``pass`` -* ``fail`` -* ``indeterminate`` - -A test has three main components. - -**DCAT description** - - A machine-readable metadata record describing the test. - -**API definition** - - An OpenAPI specification describing how to call the test service. - -**Test implementation** - - The executable service that performs the assessment. - - -.. _creating_metric_test: - -Creating a new Test Implementation ----------------------------------- -Tests can be written in any programming language provided they: - -* either: - * accept the **GUID of a digital object** as input, OR - * accept an upload of the Metadata record to be tested -* return a **JSON result object** containing the outcome following the FTR specification -* We highly recommend that Tests follow the FTR API, which defines the routes and HTTP protocols for each kind of test behaviour (e.g. discovery or execution) - - -Creating and Registering a new FAIR Metric Test DCAT Record ------------------------------------------------------------ - -Tests used with the OSTrails Benchmark Algorithms **must** be registered (using a DCAT Descriptor) in the OSTrails Test Registry. This can be done by: - -a. Authoring a test DCAT descriptor "manually", and doing a pull-request on the FAIR Metrics repository. This will result in the automatic addition of a landing page for your test, but it will not automatically notify FAIRsharing. - -or - -b. Test descriptors can be authored and registered using **FAIR Wizard**. - -1. Open FAIR Wizard and create a **new project**. -2. Select a knowledge model. -3. Enable **Filter by question tags**. -4. Choose **Test** as the artefact type. - -Two key fields must be completed. - -**Endpoint URL** - - The service endpoint that executes the test. - -**Endpoint URL Description** - - The location of the **OpenAPI description** of the test API. - -Once the questionnaire has been completed, create and submit the -resulting document. - -After processing, the test record is deposited in the -**OSTrails Assessment Component Metadata Records repository** and -indexed by FAIR Data Point. - -The test will then appear in the **FAIR Champion Test Registry** and -can be referenced, by the Test ID, in your Benchmark Configuration Spreadsheet. - -Next steps ----------- - -The next thing you probably want to do is to add this test to a benchmark. - -There is a semi-automated **community FAIR Benchmark assessments** that can be authored and executed by -the OSTrails FAIR Champion tool. - -Continue with the tutorial: - -:doc:`register-benchmark` diff --git a/docs/commons/fair/tutorials/define-benchmark-associated-metrics.rst b/docs/commons/fair/tutorials/define-benchmark-associated-metrics.rst deleted file mode 100644 index b8a1566..0000000 --- a/docs/commons/fair/tutorials/define-benchmark-associated-metrics.rst +++ /dev/null @@ -1,250 +0,0 @@ -.. _tutorial_create_fair_benchmark: - -Defining a FAIR Benchmark with its Associated Metrics -===================================================== - -This tutorial explains how to create a **community FAIR Benchmark** and -any additional **Metrics** using the OSTrails FAIR Assessment framework. - -You will start from the *OSTrails FAIR Assessment – Conceptual Requirements* -template and work through it to produce a **Benchmark narrative** describing -how your community interprets the FAIR Principles for a specific type of -digital object. - -By the end of this tutorial you will have: - -* a completed **community FAIR Benchmark narrative** -* a defined set of **FAIR Metrics** -* any required **community-specific specialised Metrics** - -For an overview of the process, see :ref:`benchmark_workflow`. - -.. _benchmark_prerequisites: - -Prerequisites -------------- - -Before starting you should: - -* Download the - `OSTrails FAIR Assessment – Conceptual Requirements template - `_. -* Be familiar with the **FAIR Principles**. -* Identify the **community or discipline** for which the Benchmark will apply. - -.. _benchmark_workflow: - -Workflow overview ------------------ - -Creating a FAIR Benchmark typically involves the following steps: - -1. :ref:`copy_template` -2. :ref:`define_benchmark` -3. :ref:`review_generic_metrics` -4. :ref:`define_specialised_metrics` -5. :ref:`review_benchmark` -6. :ref:`register_benchmark` - -Each step is described in the sections below. - -.. _copy_template: - -Step 1 – Copy the OSTrails template ------------------------------------ - -Begin by making a working copy of the **OSTrails FAIR Assessment – -Conceptual Requirements template**. - -The template provides a structured format for describing: - -* the **scope of the Benchmark** -* the **digital objects being assessed** -* the **Metrics used to evaluate FAIRness** -* the **community standards and practices** that apply - -Once the template has been downloaded and renamed, you should -work through your Benchmark narrative document sequentially, -completing each section with information relevant to your community. - -Proceed to -:ref:`define_benchmark`. - -.. _define_benchmark: - -Step 2 – Define the community Benchmark ---------------------------------------- - -The **Benchmark** section provides the narrative description of how -FAIR is interpreted for your community. - -Complete the Benchmark description by specifying: - -**Benchmark name** - - A short, descriptive title for the Benchmark. - -**Description** - - A concise explanation of the purpose of the Benchmark and the - community it serves. - -**Applicability** - - Define clearly: - - * the **type of digital object** being assessed - (for example datasets, workflows, software, or metadata records) - * the **disciplinary scope** of the Benchmark - -**Related resources** - - List any standards, repositories, policies, or vocabularies that - support FAIR practice in your community. - -The goal of this section is to describe **what FAIR means in practice -for the community and its digital objects**. - -Next, review the Metrics available in your Benchmark narrative as described in -:ref:`review_generic_metrics`. - -.. _review_generic_metrics: - -Step 3 – Review the generic FAIR Metrics ----------------------------------------- - -Your Benchmark narrative includes **generic Metrics** aligned with the -FAIR Principles. These are designed to be broadly applicable across many -disciplines. - -For each Metric card in your Benchmark narrative: - -1. Read the description of the Metric. -2. Decide whether it satisfies your community requirements. -3. Select the appropriate option in your Benchmark narrative: - - * ``This generic Metric is sufficient for our needs`` - * ``This generic Metric is not sufficient for our needs`` - * ``This principle is not applicable to our definition of FAIR`` - -Generic Metrics commonly address topics such as: - -* persistent identifiers -* structured metadata -* links between data and metadata -* indexing for discovery -* open and standardised access protocols - -In many cases these generic Metrics can be adopted without modification. - -If a generic Metric does not fully capture community practice, define a -specialised Metric as described in -:ref:`define_specialised_metrics`. - -.. _define_specialised_metrics: - -Step 4 – Define specialised Metrics where required --------------------------------------------------- - -Some FAIR principles require **community-specific interpretation**. -Where the generic Metric does not adequately represent community -practice, define a **specialised Metric**. - -Specialised Metrics are commonly required for principles such as: - -* **I2 – Use of FAIR vocabularies** -* **R1.2 – Provenance** -* **R1.3 – Community standards** - -When defining a specialised Metric, include the following elements. - -**Metric name** - - A short descriptive title. - -**Metric description** - - A clear explanation of what is being evaluated and why it supports - FAIR. - -**Assessment criteria** - - The conditions that must be met for the Metric to pass. - -**Related standards or resources** - - References to relevant community standards, vocabularies, or - policies. - -**Examples** - - Where possible, provide: - - * a positive example - * a negative example - * an indeterminate example - -These examples help both implementers and assessment tools understand -how the Metric should be applied. - -Once specialised Metrics have been defined, review the Benchmark as -described in :ref:`review_benchmark`. - -.. _review_benchmark: - -Step 5 – Review the completed Benchmark ---------------------------------------- - -After completing all sections of your Benchmark narrative: - -* Review the Benchmark with **community experts or stakeholders**. -* Check that **all relevant FAIR principles are addressed**. -* Ensure that any referenced **standards, vocabularies, or - repositories** are clearly identified. - -The completed document now represents the **conceptual FAIR Benchmark** -for your community. - -The final step is to register the Benchmark and Metrics as described in -:ref:`register_benchmark`. - -.. _register_benchmark: - -Step 6 – Register the Benchmark and Metrics -------------------------------------------- - -To enable reuse and interoperability, the Benchmark and its Metrics -should be converted from a narrative document into both FTR specification documents and registered in community registries such as -`FAIRsharing `_. - -Conversion to FTR and registration with FAIRsharing should include: - -* the **Benchmark description** -* each **specialised Metric** -* references to any **standards, databases, or vocabularies** - -Registering in FAIRsharing these components allows: - -* FAIR assessment tools to discover and implement the Metrics -* other communities to reuse or adapt the Benchmark -* FAIR assessment results to be compared across tools - -More information on how to create formal FTR specification documents and registering them with FAIRsharing is available in our tutorials on specifying and registering `benchmarks `_ and `metrics `_. - -Next steps ----------- - -Once the conceptual Benchmark has been created, the next stages -typically include: - -* implementing **machine-actionable Metric tests** -* defining **assessment workflows** -* applying the Benchmark to **evaluate digital objects** - -This converts the conceptual definition into a working -**FAIR assessment framework**. - -Continue with the tutorial: - -:ref:`tutorial_create_metric_tests` - diff --git a/docs/commons/fair/tutorials/define-run-scoring-algorithm.rst b/docs/commons/fair/tutorials/define-run-scoring-algorithm.rst deleted file mode 100644 index 236627d..0000000 --- a/docs/commons/fair/tutorials/define-run-scoring-algorithm.rst +++ /dev/null @@ -1,220 +0,0 @@ -.. _tutorial_fair_benchmark_algorithm: - -Defining and Running a FAIR Benchmark Assessment Algorithm -=========================================================== - -This tutorial explains how to define and run a **FAIR Benchmark Assessment -Algorithm** using the OSTrails tool **FAIR Champion**. - -A Benchmark Assessment Algorithm combines multiple **FAIR Metric Tests** -and scoring rules to assess the FAIRness of a digital object according to -a specific community Benchmark. - -In this tutorial you will: - -* run an existing Benchmark assessment -* create your own **Benchmark Configuration Spreadsheet** -* register the algorithm with FAIR Champion -* run the algorithm on one or more digital objects - -By the end of this tutorial you will have a working **FAIR Benchmark -Assessment Algorithm** that can be executed within FAIR Champion. - -.. _benchmark_algorithm_prerequisites: - -Prerequisites -------------- - -Before starting you should have completed: - -* :ref:`tutorial_create_fair_benchmark` -* :ref:`tutorial_create_metric_tests` - -And have access to: - -* The **FAIR Champion assessment service**. -* Your **Benchmark definition** and associated metrics. - -Some steps also require access to: - -* `FAIR Champion `_ -* `FAIR Wizard `_ -* `OSTrails Test Registry `_ - -.. _benchmark_algorithm_workflow: - -Workflow overview ------------------ - -Creating and running a Benchmark Assessment Algorithm (BAA) involves the -following steps: - -1. :ref:`run_existing_algorithm` -2. :ref:`create_configuration_spreadsheet` -3. :ref:`register_algorithm` -4. :ref:`run_single_assessment` -5. :ref:`run_multiple_assessments` - -Each step is described in the sections below. - -.. _run_existing_algorithm: - -Step 1 – Run an existing Benchmark assessment ---------------------------------------------- - -Before creating a new algorithm it is helpful to run an existing one to -confirm that the assessment service is working. - -1. Open the FAIR Champion assessment interface: - - https://tools.ostrails.eu/champion/assess/algorithms/new - -2. Select a **Benchmark Configuration Spreadsheet URI** from the list. - -3. Enter the **GUID of the digital object** to be assessed. - -4. Click **Run Benchmark Quality Assessment**. - -After a few seconds the results will be displayed on screen. - -The output typically shows: - -* individual test results -* weighted scores -* conclusions -* optional links to guidance for Conditions that were not met - -Running an existing algorithm confirms that the FAIR Champion service -is functioning correctly. - -You can now proceed to creating your own configuration spreadsheet as -described in :ref:`create_configuration_spreadsheet`. - -.. _create_configuration_spreadsheet: - -Step 2 – Create a Benchmark Configuration Spreadsheet ------------------------------------------------------ - -Benchmark Assessment Algorithms for FAIR Champion are defined -using a **configuration spreadsheet**. - -You can begin by copying the **Generic Algorithm spreadsheet** available -from the FAIR Champion assessment interface. - -The spreadsheet contains three sections. - -**General metadata** - - Describes the algorithm using DCAT properties. - -**Test references** - - Lists the FAIR Metric Tests used by the algorithm and assigns weights - to their outputs. - -**Conditions and calculations** - - Defines the scoring logic based on the test results. - Links to guidance may be included for some or all of the conditions. - -General rules for configuration spreadsheets: - -* Currently only **Google Sheets** are supported. -* The spreadsheet must be **publicly readable**. -* Headers must be used **exactly as provided in the template**. -* Each section must be separated by **one empty line**. -* The URIs of the tests must resolve to a **DCAT DataService record** - describing the test. - -A list of available tests can be found in the -`OSTrails Test Registry `_. - -Calculations reference tests by their **abbreviation**. Expressions use -Ruby-style syntax, for example:: - - test_identifier_1 + test_identifier_2 > 3 - -Each calculation returns either **true** or **false**, which determines -the narrative result associated with that condition. - -Once the spreadsheet is complete it must be registered with FAIR -Champion as described in :ref:`register_algorithm`. - -.. _register_algorithm: - -Step 3 – Register the Benchmark Assessment Algorithm ----------------------------------------------------- - -After creating your configuration spreadsheet you must register it so -that FAIR Champion can use it. - -1. Ensure the spreadsheet is **publicly accessible**. -2. Copy the **URI of the spreadsheet**. -3. Register the spreadsheet with FAIR Champion via the - 'Register a new Benchmark Quality Assessment Algorithm' option - on the home page. - -FAIR Champion will convert the spreadsheet into a registered -**Benchmark Assessment Algorithm**. - -You can verify that the registration succeeded by checking the -**FAIR Data Point index**, where the algorithm should appear with -status **Active**. - -Once the algorithm is registered it will appear in the list of -available Benchmark algorithms within the FAIR Champion interface. - -You can now run the algorithm as described in -:ref:`run_single_assessment`. - -.. _run_single_assessment: - -Step 4 – Run an assessment using your algorithm ------------------------------------------------ - -To run an assessment using your own algorithm: - -1. Return to the FAIR Champion assessment interface: - - https://tools.ostrails.eu/champion/assess/algorithms/new - -2. Select your **Benchmark Configuration Spreadsheet URI** from the - algorithm list. - -3. Enter the **GUID of a digital object**. - -4. Click **Run Benchmark Quality Assessment**. - -If the configuration spreadsheet has been correctly defined and -registered, the results will be displayed in the same way as when -running an existing algorithm. - -This confirms that your **Benchmark Assessment Algorithm** is working -correctly. - -.. _run_multiple_assessments: - -Step 5 – Run assessments on multiple objects --------------------------------------------- - -To run assessments on multiple digital objects you can use the -**benchmark runner** application. - -1. Clone the repository:: - https://github.com/cessda/cessda.cmv.benchmark-runner - -2. Build the application:: - mvn compile - -3. Edit the ``guids.txt`` file so that it contains the GUIDs of the - digital objects to be assessed. - -4. Run the application using:: - mvn exec:java -Dexec.args= - -where ```` is the URL of your registered Benchmark -algorithm. - -The terminal will display progress as each object is assessed. - -Results for each GUID are written to the ``results`` directory. diff --git a/docs/commons/fair/tutorials/deploy-champion.rst b/docs/commons/fair/tutorials/deploy-champion.rst deleted file mode 100644 index 3c24dda..0000000 --- a/docs/commons/fair/tutorials/deploy-champion.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. _deploy-champion: - -How to deploy Champion myself -=============================== - -You only need to do this if you are testing records that are, for example, behind a firewall. Most of the time you -will simply go to `Champion `_ - -If you feel the need to checkout the code, go to: -https://github.com/OSTrails/FAIR-Champion/ - -However, you can simply access the latest Docker image, using the following docker-compose file: - - services: - - champion: - image: markw/fair-champion:0.3.0 - environment: - - TESTHOST=https://tests.ostrails.eu/tests/ - - CHAMPHOST=http://localhost:8383/ - ports: - - "8383:4567" - - - swagger-converter: - image: swaggerapi/swagger-converter:latest - container_name: swagger-converter - -Find the latest versioned tag for Champion at `Dockerhub `_ - -The following environment variables should be set (in the docker-compose, probably) - - - RACK_ENV='development' - - TEST_HOST='https://tests.ostrails.eu/tests' # this is probably now deprecated, as per March 2026 - - CHAMP_HOST=https://tools.ostrails.eu/champion' # the URL of your own Champion instance - - FDPINDEX_SPARQL='https://tools.ostrails.eu/repositories/fdpindex-fdp' # THIS IS CRITICAL! - - FDPINDEXPROXY='https://tools.ostrails.eu/fdp-index-proxy/proxy' # if you plan to regisgter new tests or benchmarks using your local copy - - CHAMPION_HOST='https://tools.ostrails.eu/champion' # probably redundant to the one above. I'll check - - -That's all! diff --git a/docs/commons/fair/tutorials/find-metrics-and-benchmarks.rst b/docs/commons/fair/tutorials/find-metrics-and-benchmarks.rst deleted file mode 100644 index 13b8af9..0000000 --- a/docs/commons/fair/tutorials/find-metrics-and-benchmarks.rst +++ /dev/null @@ -1,239 +0,0 @@ -.. _find-metrics-and-benchmarks: - -Finding and Reusing Metrics and Benchmarks -========================================== - -This tutorial explains how to discover FAIR metrics and benchmarks using -two complementary routes: the FAIRassist registry and FAIRsharing's own -search and browse features. Once you have found a metric of interest, you -can learn how to locate any tests that implement it in -`find-test-for-digital-object.rst `_. - -What are metrics and benchmarks? ---------------------------------- - -FAIRsharing registers the conceptual components of the FAIR assessment -ecosystem within its FAIRassist registry. This includes: - -- **Principles** — are designed to be subject- and implementation-agnostic criteria or high-level goals that may be refined for particular communities using the Assess IF (and are stored within FAIRsharing's - Standards registry, e.g. the - `FAIR Principles `_). -- **Metrics** — measurable criteria that interpret a Principle, - specifying what must be true of a digital object for that Principle to - be satisfied. -- **Benchmarks** — curated sets of Metrics that together define what - "FAIR" means in practice for a particular community, tool, or use case. - -For more background on the FAIRassist registry and how it aligns with -the FAIR Testing Resource (FTR) vocabulary, see the -`FAIRsharing documentation on registry types -`_. - - -A note on object types ------------------------ - -Both sections of this tutorial describe a number of ways to filter metrics and -benchmarks, including by the type of digital object they are designed to assess. -Before using this filter, it is worth reviewing the full controlled -vocabulary of object types in FAIRsharing, available at -`https://fairsharing.gitbook.io/fairsharing/record-sections-and-fields/general-information/object-types -`_. - -The controlled vocabulary includes specific types such as dataset, -software application, model, terminology artifact, protocol or workflow, -and several others. Two general-purpose types are also available: - -- *object type agnostic* — use this when a metric or benchmark is - relevant across all types of digital object. -- *other object type* — use this only when the object type is not - covered by any of the other terms in the vocabulary and the resource - is not agnostic. - -.. note:: - - The term *object type not found* appears on a small number of older - deprecated records where the original object type could not be - determined during curation. This is an administrative term and is - not relevant when searching for metrics or benchmarks; you can - safely ignore it. - -Take time to review the full vocabulary before selecting a type to -filter by, as the most appropriate choice may not always be immediately -obvious. For example, a metric that is relevant to all digital objects -should be found using *object type agnostic* rather than by listing -individual types. - - -Section 1: Metric discovery via FAIRassist -------------------------------------------- - -The `FAIRassist registry `_ is the -primary entry point for discovering metrics and benchmarks. Although -FAIRassist is part of FAIRsharing, its interface is purpose-built for -exploring these record types, and presents search results in a tabular -format that gives you an overview of the full ecosystem of resources -related to a given set of metrics or benchmarks. - -FAIRassist is particularly useful for answering questions such as: - -- What assessments already exist for my subject area or for a particular - tool? -- Which standards and databases are referenced by assessments in my - domain? -- What benchmarks has a given organisation defined or contributed to? -- Which metrics apply to a particular type of digital object? - -This search and display method provides dynamic guidance that supplies extra context around FAIR -benchmarks, and transparent definitions of metrics to support their -correct reuse. - - -Using the filters -~~~~~~~~~~~~~~~~~ - -The FAIRassist registry provides five filters that can be used -individually or in combination. - - -Record type -^^^^^^^^^^^ - -Select whether you want to retrieve Metrics or Benchmarks (or both). -This is the broadest filter and must be used to ensure the appropriate usage of later filters. - - -Object type -^^^^^^^^^^^ - -Metrics can be filtered by the type of digital object they are designed -to assess. Before using this filter, review the full controlled -vocabulary of object types described in the `note on object types -<#a-note-on-object-types>`_ above and in the `FAIRsharing object types -documentation -`_, -to ensure you select the term that most accurately reflects your needs. -This may include *object type agnostic* for metrics that apply across -all digital object types, or *other object type* for those covering -object types not represented elsewhere in the vocabulary. - - -Tool -^^^^ - -Metrics can be filtered by the assessment tool that utilises them. -Currently available tool options include FOOPS! and FAIR Champion. This -filter is useful when you are working with a specific tool and want to -understand which metrics that tool draws on, or when you want to find -metrics that are already implemented in a tool you trust. - - -Subject -^^^^^^^ - -Both metrics and benchmarks can be filtered by subject area. The -subjects available reflect the FAIRsharing subject hierarchy, which you -can browse at `https://fairsharing.org/browse/subject -`_. Use this filter to narrow -your results to metrics and benchmarks that are relevant to your -research domain. - - -Organisation -^^^^^^^^^^^^ - -Both metrics and benchmarks can be filtered by the organisation -associated with them. This is useful when you want to find all metrics -or benchmarks developed or maintained by a particular institution, -project, or working group. - - -A worked example: finding metrics linked to CESSDA -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To illustrate how these filters work together, the following URL -retrieves all metrics associated with the CESSDA organisation and -linked to the FAIR Principles: - -`https://fairassist.org/registry?search=(principle=The+FAIR+Principles%26organisations=cessda%26recordType=metric_ids `_ - -The results are displayed in tabular sections, one per record type, -allowing you to quickly scan the set of metrics that CESSDA has -contributed to or is associated with, alongside contextual information -about each one. From any row in the results you can navigate directly -to the full FAIRsharing record for that metric. - - -Section 2: Metric discovery via FAIRsharing --------------------------------------------- - -FAIRsharing's own search and browse tools can also be used to find -metrics and benchmarks. This route is particularly useful when you want -to combine FAIRassist record types with other FAIRsharing filters, such -as status or object type, or when you want to use the advanced search to -build a precise query. Full documentation on FAIRsharing's search -features is available at -`https://fairsharing.gitbook.io/fairsharing/how-to/searching-and-browsing -`_. - - -Simple search -~~~~~~~~~~~~~ - -The FAIRsharing simple search bar searches across all record types, -including metrics and benchmarks. Entering a keyword such as a FAIR -principle identifier, a domain term, or the name of a metric will return -all matching records. You can then use the faceted filters on the left of -the results page to narrow results to the FAIRassist registry, and -further refine by object type or a large number of other facets as required. - - -Advanced search -~~~~~~~~~~~~~~~ - -The advanced search gives you precise control over which record types, -statuses, object types, and fields are queried. For example, one or more object types -can be selected as part of the advanced search query construction, -allowing you to combine an object type filter with other criteria such -as record type, status, and associated tests. Before selecting an object -type, review the full controlled vocabulary described in the `note on -object types <#a-note-on-object-types>`_ above, to ensure you are using -the most appropriate term. - -The following examples show how to retrieve specific subsets of -FAIRassist records. - -To retrieve all metrics with a status of Ready or In Development: - -`https://fairsharing.org/advancedsearch?operator=_and&fields=%28operator%3D_and%26fairassisttype%3Dmetric%26status%3Dready%2Bin_development%29 `_ - -To retrieve all benchmarks with a status of Ready or In Development: - -`https://fairsharing.org/advancedsearch?operator=_and&fields=%28operator%3D_and%26fairassisttype%3Dbenchmark%26status%3Dready%2Bin_development%29 `_ - -To retrieve all Ready or In Development metrics that have at least one -associated test — a useful starting point if you are looking for metrics -that are already implemented and ready for use: - -`https://fairsharing.org/advancedsearch?operator=_and&fields=%28operator%3D_and%26fairassisttype%3Dmetric%26status%3Dready%2Bin_development%26associatedTests%3Dtrue%29 `_ - - -Browse by subject -~~~~~~~~~~~~~~~~~ - -If you prefer to explore visually, the FAIRsharing subject browser at -`https://fairsharing.org/browse/subject `_ -allows you to navigate a hierarchical sunburst diagram of subject areas. -Selecting a subject will show you all FAIRsharing records tagged with -that subject or any of its child terms, across all registries including -FAIRassist. - - -Next steps ----------- - -Once you have identified a metric of interest, you may want to find any -tests that implement it. See `find-test-for-digital-object.rst `_ for a -step-by-step guide. - - diff --git a/docs/commons/fair/tutorials/find-test-for-digital-object.rst b/docs/commons/fair/tutorials/find-test-for-digital-object.rst deleted file mode 100644 index 7dc78b6..0000000 --- a/docs/commons/fair/tutorials/find-test-for-digital-object.rst +++ /dev/null @@ -1,250 +0,0 @@ -.. _find-test-for-digital-object: - -How to find a Test for my digital object -======================================== - -This tutorial covers how to find a Test using FAIRsharing (Test linked to a Metric), and how to find Tests using FAIR Champion. - - -FAIRsharing: Finding a Test Linked to a Metric ------------------------------------------------ - -This section explains how to navigate to a metric record in FAIRsharing -and locate any tests that implement it. If you have not yet found a -metric of interest, see `find-metrics-and-benchmarks `_ first. - -Background: how tests relate to metrics ------------------------------------------ - -FAIRsharing registers the conceptual components of the FAIR assessment -ecosystem — Principles, Metrics, and Benchmarks. Tests, which are the -concrete implementations of Metrics, are registered separately in FAIR -Champion at `https://tools.ostrails.eu/champion/tests/ -`_. However, FAIRsharing -Metric records provide a cross-reference to any tests that implement -them via the Associated Tests field in the record's Additional -Information section. - -Associated tests are cross-referenced in two ways: - -- At regular intervals, the FAIRsharing team automatically updates - the Associated Tests field by querying FAIR Champion and other - registered test sources. -- Metric maintainers may also add test URLs manually at any time. - -.. note:: - - FAIRsharing stores URLs pointing to tests; it does not store the - tests themselves. Each URL may point to an individual test or to a - search URL that retrieves all tests implementing that metric. An - optional free-text note field is available alongside each URL to - provide further context. - -For full documentation on the Associated Tests field and the related -Positive and Negative Examples fields, see the `FAIRsharing -documentation on metric tests and examples -`_. - - -A note on object types ------------------------ - -Metrics in FAIRsharing are tagged with one or more object types that -describe the kind of digital object the metric is designed to assess. -When looking for a test linked to a metric, it is therefore helpful to -have a clear understanding of what type of digital object you are -working with, so that you can identify the most relevant metrics before -looking for their associated tests. - -The full controlled vocabulary of object types is available at -`https://fairsharing.gitbook.io/fairsharing/record-sections-and-fields/general-information/object-types -`_. -The vocabulary includes specific types such as dataset, software -application, model, terminology artifact, and protocol or workflow, -among others. Two general-purpose types are also available: - -- *object type agnostic* — used for metrics that apply across all - types of digital object. -- *other object type* — used only when the object type is not covered - by any other term in the vocabulary and the resource is not agnostic. - -.. note:: - - The term *object type not found* appears on a small number of older - deprecated records where the original object type could not be - determined during curation. This is an administrative term and is - not relevant when searching for metrics; you can safely ignore it. - -Review the full vocabulary before filtering, as the most appropriate -choice may not always be immediately obvious. For example, a metric -relevant to all digital objects should be found using *object type -agnostic* rather than by listing individual types. - - -Step 1: Open a metric record ------------------------------ - -You can arrive at a metric record in either of two ways. - - -Via FAIRassist -~~~~~~~~~~~~~~ - -Navigate to the `FAIRassist registry `_ -and use the filters to find a metric relevant to your needs, as -described in `find-metrics-and-benchmarks `_. Click on any metric -in the results to open its full FAIRsharing record. - - -Via FAIRsharing directly -~~~~~~~~~~~~~~~~~~~~~~~~ - -Use the FAIRsharing search or advanced search to find a metric, as -described in `find-metrics-and-benchmarks `_. Alternatively, if -you already have the DOI or URL of a specific metric, navigate directly -to that record. For example: - -- `FAIR Metric - A version IRI is declared in the ontology metadata - `_ - (``https://doi.org/10.25504/FAIRsharing.99c9f7``) -- `FAIR Metric - Metadata Contains CESSDA Provenance Information - `_ - (``https://doi.org/10.25504/FAIRsharing.4e4752``) - - -Step 2: Navigate to the Additional Information section -------------------------------------------------------- - -Once you have a metric record open, scroll down past the General -Information section. FAIRsharing record pages are organised into -tabbed or sectioned areas; look for the Additional Information -section or tab. Within it, you will find the following subsections -specific to metric records: - -- Associated Tests -- Positive Examples -- Negative Examples - -.. note:: - - The Associated Tests, Positive Examples, and Negative Examples - subsections appear only on records within the FAIRassist registry - (i.e. Metric records). They are not present on standard database, - policy, or other FAIRsharing record types. - - -Step 3: View the Associated Tests ------------------------------------ - -The Associated Tests subsection lists one or more URLs, each linking -to a test or set of tests that implement the metric. Each entry may -also include a free-text note providing additional context about the -test or its scope. - - -Example 1: a metric with a FOOPS! test -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The metric `FAIR Metric - A version IRI is declared in the ontology -metadata `_ includes an -Associated Tests entry linking to a FOOPS! test. FOOPS! is an automated -tool for assessing the FAIRness of ontologies. In this case, the test -URL has been added directly by the metric maintainer rather than via -automated cross-referencing. - -Opening the metric record and navigating to Additional Information > -Associated Tests will show you the FOOPS! test URL, from which you can -access the test itself and understand how it operationalises the metric. - - -Example 2: a metric with a FAIR Champion test -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The metric `FAIR Metric - Metadata Contains CESSDA Provenance -Information `_ includes an -Associated Tests entry linking to a test registered in FAIR Champion at -`https://tools.ostrails.eu/champion/tests/ -`_. - -FAIR Champion is a tool within the OSTrails ecosystem that registers and -executes FAIR tests. Opening the metric record and navigating to -Additional Information > Associated Tests will show you the FAIR -Champion test URL. Following that link takes you to the test record in -FAIR Champion, where you can view the test specification and, where -supported, execute it against a digital object. - -.. note:: - - If a metric record's Associated Tests field is empty, it does not - necessarily mean that no test exists for that metric — it may not - yet have been cross-referenced. You can search for tests directly - in FAIR Champion at `https://tools.ostrails.eu/champion/tests/ - `_, or contact the - metric maintainer whose details appear in the record's General - Information section. - - -Step 4: Follow the test URL ----------------------------- - -Once you have identified a test URL in the Associated Tests field, -follow it to access the test itself. For tests registered in FAIR Champion, the full list of available tests -is at `https://tools.ostrails.eu/champion/tests/ -`_. - - -Finding metrics that already have tests ------------------------------------------ - -If you want to start from a list of metrics that are confirmed to have -at least one associated test, the following FAIRsharing advanced search -URL retrieves all Ready or In Development metrics with at least one -associated test: - -`https://fairsharing.org/advancedsearch?operator=_and&fields=%28operator%3D_and%26fairassisttype%3Dmetric%26status%3Dready%2Bin_development%26associatedTests%3Dtrue%29 `_ - -This is a practical starting point if you are building or evaluating a -FAIR assessment pipeline and want to work only with metrics that have -concrete implementations available. - - -Further reading ---------------- - -- `find-metrics-and-benchmarks `_ — how to discover metrics and - benchmarks via FAIRassist and FAIRsharing. -- `FAIRsharing documentation on metric tests and examples - `_ -- `FAIRassist registry `_ -- `FAIR Champion test registry `_ - -Finding a Test in FAIR Champion -------------------------------- -`FAIR Champion `_ is a tool/framework designed to evaluate and assess digital objects based on FAIR metrics. More information can be found `here `_. - -FAIR Champion also allows you to discover FAIR Assessment Components, such as Tests, that are relevant to your needs. - -Searching by keywords ---------------------- -When accessing `its landing page `_, FAIR Champion provides a set of links to different entries. -By clicking on the first option, *"List all Tests in OSTrails Registry"*, a browser interface will open, allowing you to search for Tests based on relevant terms. - -You may want to look for a Test you previously identified using the FAIRassist tool (described in the previous section of this tutorial), or you can discover Tests from scratch if you do not already know their exact name. - -1. Enter keywords related to your use case. - The system will return a list of matching Tests based on their content, such as name and description. - -2. Once you obtain the list of matching Tests, each result includes a short description to help you understand what the Test evaluates. - You can use this information to quickly assess whether a Test is relevant to your needs. - Additional information, such as the **Test ID** for the Benchmark Algorithm Spreadsheet, is available in the *Additional Details* drop-down. - The option to run the Test is also available via the *Execute Test* drop-down. - -Refining your search --------------------- -You can narrow down your results in two ways: - -A. By refining your keywords to make them more specific. - -B. By using FAIRassist beforehand to perform a more targeted search. - This is especially useful if you have already identified a Test and want to locate it more quickly, while accessing its description, additional details, and execution options. - diff --git a/docs/commons/fair/tutorials/host-deploy-test.rst b/docs/commons/fair/tutorials/host-deploy-test.rst deleted file mode 100644 index 25c69b1..0000000 --- a/docs/commons/fair/tutorials/host-deploy-test.rst +++ /dev/null @@ -1,60 +0,0 @@ -How host/deploy a test -========================= - -The easiest way is to ask someone from OSTrails WP3 to write the test for you, and host it on the OSTrails Infrastructure. -This helps keep tests quality-controlled, consistent, and with reliable up-time. - -If you really want to do it yourself, you need: - -1. Understand (or author) the Metric that you are going to test. **this is a pre-requisite for writing the test!** -2. Access to a server -3. Coding knowledge in any language -4. Understanding of the rules for Linked Data -5. Optimally, you would also use a Linked Data library from your language to reduce errors; however the data structures can simply be templated. -6. Understanding of the FTR Vocabulary, and specifically the pieces related to a TestResult object -7. Understand how to author an OpenAPI Service Descriptor -8. Either understand a DCAT DataService object, or use the Test Wizard to author this object - -Tests have two "modalities": - -1. A test can consume a GUID, and use normal identifier resolution on that to retrieve metadata -2. A test can consume an uploaded metadata record - -The API for option 1 is to consume the following JSON data structure: - -.. code-block:: json - - { "resource_identifier": "GUID" } - - -The API for option 2 is to follow this OpenAPI3 pattern for file upload: - -.. code-block:: yaml - - requestBody: - required: true - content: - multipart/form-data: - schema: - type: object - required: [file] - properties: - file: - type: string - format: binary - description: The uploaded metadata. - encoding: - file: - contentType: application/json - - -Test outputs must follow the FTR schema, and at a minimim must include - -1. The identifier of the metadata object that was tesated -2. The Metric that is associated with the Test -3. The "value" of the output (pass/fail/indeterminate are the only valid outputs) -4. A reference to the TestExecution, and metadata about that (e.g. test identifier, date, version, etc) - -Test outputs may optimally include a reference to a Guidance Object. Guidance Objects are added during test execution, when a test detects an error. They are intended to help the metadata author avoid the error. - -Guidance Objects are still under development, so are not deeply documented here. diff --git a/docs/commons/fair/tutorials/how-comply-ftr.rst b/docs/commons/fair/tutorials/how-comply-ftr.rst deleted file mode 100644 index 98ff753..0000000 --- a/docs/commons/fair/tutorials/how-comply-ftr.rst +++ /dev/null @@ -1,158 +0,0 @@ -FAIR Test Results (FTR) Developer Tutorial -========================================== - -The FAIR Test Results (FTR) specification provides a standard way to define, -execute, and expose FAIR assessments in a machine-readable and interoperable way. - -FTR is built around four core entities: - -- **Metric**: A measurable FAIR principle or rule -- **Benchmark**: A collection of metrics -- **Test**: An implementation that evaluates a metric -- **Scoring Algorithm**: A method to aggregate test results into a score - -For full reference, see: -https://docs.ostrails.eu/en/latest/commons/fair/fair-test-results-vocabulary-ftr.html - - -Step 1 - Identification of Metrics ----------------------------------- - -Most FAIR assessment tools already include a set of tests. The first step is to -analyse those tests and determine whether they correspond to existing FAIR metrics. These metrics can exist or not - -The first step -is to analyse these tests and determine whether they correspond to existing -metrics defined in the FAIR Sharing framework. - -.. - If a test can be mapped to an existing metric, follow this tutorial :doc:`others-use-my-metrics` - -- If no suitable metric exists, you will need to create new ones by following :doc:`register-metric` - -This step is essential to ensure interoperability and reuse of existing community standards whenever possible. - -Guidelines: - -- Prefer **reusing existing metrics** to ensure interoperability. -- Only create new metrics when necessary -- Ensure each metric is clearly defined and documented - -Resources: - -.. - Reuse metrics :doc:`others-use-my-metrics` - -- Create new metrics :doc:`register-metric` - -Step 2 - Grouping Metrics into a Benchmark ------------------------------------------- - -A **benchmark** is a logical grouping of metrics used to evaluate a resource. - - -Key considerations: - -- Benchmarks should be **coherent and meaningful** -- You can combine: - - Existing metrics - - Newly created metrics -- Benchmarks define the **scope of evaluation** - -Resource: - -- :doc:`register-benchmark` - -Step 3 - API Creation ---------------------- - -FTR requires a standardised API to expose: - -- Tests -- Metrics -- Results -- Scores - -Think of FTR as a **contract** your API must follow. - - -Implementation options: - -- Adapt an existing API -- Build a new API following FTR specification - -Key requirements: - -- Consistent data model -- Standardised endpoints -- Machine-readable outputs (e.g., JSON-LD) - -Step 4 - Test Creation ----------------------- - -Each metric must have at least one corresponding **test**. - -A test: - -- Implements the logic to evaluate a metric (it is code) -- Produces a result in FTR format - - -Requirements: - -- Align test logic with metric definition -- Ensure reproducibility -- Provide clear outputs - -Resource: - -- :doc:`create-test-following-ftr` - -Step 5 - Scoring Algorithm Implementation ------------------------------------------ - -The **scoring algorithm** aggregates test results into a final score. - - -Responsibilities: - -- Combine multiple test results -- Produce an overall FAIR score -- Ensure transparency and reproducibility - -Best practices: - -- Document your scoring method -- Keep it interpretable -- Avoid hidden logic - -Resource: - -- :doc:`define-run-scoring-algorithm` - -Step 6 - Deployment -------------------- - -Once all components are implemented, deploy your FTR-compliant service. - - -Checklist: - -- API is publicly accessible -- Endpoints follow FTR specification -- Tests execute correctly -- Scores are computed consistently - -Validation: - -- :doc:`run-existing-test` - - -Conclusion ----------- - -By following this tutorial, you will: - -- Align your tool with FTR -- Enable interoperability with other FTR-compliant services -- Provide reproducible and transparent FAIR evaluations - - diff --git a/docs/commons/fair/tutorials/register-benchmark.rst b/docs/commons/fair/tutorials/register-benchmark.rst deleted file mode 100644 index 9099824..0000000 --- a/docs/commons/fair/tutorials/register-benchmark.rst +++ /dev/null @@ -1,213 +0,0 @@ -.. _register-benchmark: - -How to register a Benchmark -============================ - -This tutorial explains how to register a **community FAIR Benchmark** using the OSTrails FAIR Assessment framework. - -A Benchmark is a community-specific grouping of a set of Metrics that provides a narrative of those particular ways in which that community defines FAIR for assessment purposes. -For more information, check `the FAIR Testing Resource (FTR) vocabulary `_. - -There are two ways to register a Benchmark. The first is to use the `FAIR Wizard authoring tool `_, a questionnaire-based knowledge model designed to collect and structure metadata for FAIR Assessment Components, including Benchmarks. It auto-generates FTR metadata and registers it in FAIRsharing for you. The second is to register your Benchmark directly with FAIRsharing. This tutorial covers both options. - -FAIR Wizard ------------- - -.. _register_benchmark_prerequisites: - -Prerequisites -------------- - -Before starting you should: - -* Have a defined set of **FAIR Metrics**, as well as any required **community-specific specialised Metrics**. You may find the tutorial at `define-benchmark-associated-metrics.rst `_ useful. -* Have a completed **community FAIR Benchmark narrative** definition, aligned with the community or discipline for which it will apply. This can be done by following the tutorial at `define-benchmark-associated-metrics.rst `_. This narrative definition of FAIR will contain a description of your benchmark -* Have access to the `FAIR Wizard authoring tool `_. - -.. _create_benchmark_project: - -Step 1 – Create a Benchmark project in the FAIR Wizard authoring tool ---------------------------------------------------------------------- -1. Go to `the dedicated environment for this questionnaire `_. -2. Register yourself or log in if you already have access. -3. Navigate to Projects and click Create to start a new project. -4. Name your project and use the "**FAIR Assessment Authoring Tool** - Questionnaire for creating FAIR Assessment Components" template as Knowledge Model. -5. Enable **Filter by question tags**. -6. Choose **Benchmark** as the artefact type. - -By doing this, the tool will create a Benchmark-tailored questionnaire. - -.. _fill_out_benchmark_questionnaire: - -Step 2 – Fill in the questionnaire --------------------------------------- - -1. Read the instructions carefully. -2. Work through the form sequentially, completing each section with information relevant to the Benchmark you are defining. - -Note that there are questions that are *mandatory*, which will be required to be given an answer. Other questions are optional. -The mandatory fields that are required to define a FAIR Benchmark are: - -- ``Title`` - You should indicate the title of your Benchmark. To follow OSTrails best practices, consider using this Benchmark naming scheme: [[Principles name]] Benchmark - [[descriptive benchmark name]] - - -Examples: - - FAIR Benchmark - Assessment of Repositories and Knowledgebases (https://fairsharing.org/7162) - - FAIR4RS Benchmark - General Benchmark for RSFC (https://fairsharing.org/7056) - - FAIR Benchmark - CESSDA Data Catalogue (CDC) - -- ``Description`` - You should indicate a description of your Benchmark. - -- ``Abbreviation`` - You should indicate a single-word abbreviation for your Metric. Note that FAIR Wizard does not allow the use of spaces or any of these special characters in Benchmark/Metric/Test name abbreviations: : / ? # [ ] @ ! $ & ' ( ) * + , ; = "< > \ ^ { < > : " / \ - To follow OSTrails best practices, consider using this Metric naming scheme: - [[Principle abbrev]]B - [[short name for the benchmark]] - -Examples: - - FB - ARK - - FSB - RSFC - - FB - CESSDA - -- ``License`` - You should include a license URL for this Benchmark. Please do not include angle brackets "<>" in your response. - -- ``Version`` - You should indicate the version number you are interested in using for defining your Benchmark. - -- ``Organisation information`` - This question is mandatory for FAIRsharing submission. Your Benchmark might be associated with an institution as its creator or maintainer. - -- ``Responsable contact person`` - You should provide the name and email of a responsible contact person. You will find an ORCID-integrated browser to search for your personal information by either typing in your full name or your ORCID ID directly. - -- ``Country`` - You should indicate the country or geographical scope relevant to this Benchmark. If the Benchmark is not limited to a specific region, you can select *’Worldwide’*. - -- ``Subject`` - You should specify the application domain or area of knowledge to which the Benchmark applies. If the Metric is intended to be domain-independent, you can select *’Subject Agnostic’*. - -- ``Object type`` - You should indicate the type of digital object that the Benchmark evaluates (for example datasets, software, or workflows). If the Benchmark applies broadly, you can select Object type *’Agnostic’*. - -- ``Taxonomy`` - You should classify the Benchmark within a taxonomy. If no suitable classification is available or needed, you can select *’Not Applicable’*. - -- ``Link to a Metric`` - You should link the Benchmark to at least one Metric. Use this relationship to link to every Metric implemented by this Benchmark: `has_associated_metric `_. - -- ``Other related FAIR assessment components`` - This question might be optional or mandatory depending on the FAIR assessment component you are authoring. For Benchmarks, this question is mandatory, as it needs to have associated Metrics. - - - -**Please complete all optional sections that it is possible for you to complete. The more complete your metric, the more re-usable and FAIR it is. Incomplete metadata may delay the publishing of your Benchmark in FAIRsharing.** - - -Step 3 – Create an instance with your answers ----------------------------------------------- - -Once the questionnaire has been completed: - -1. Go to the **Documents** section in the top menu. -2. Name your document and select the latest version of the "*FAIR Assessment Authoring Tool* - Jinja2-based template for authoring and registering FAIR Assessment Components" as Document Template. -3. Choose the "Metric / Benchmark" Format option. -4. Click on *Create*. - -This will create a JSON file with your input. - -Step 4 – Submit your document --------------------------------------- - -Now, you can review the document with your answers to the questionnaire, by clicking on it, which will initiate the download of the file. Once you're happy with it, you're ready to submit your document: - -4. In the **Documents** section, click the three dots icon (⋯) beside your document. -5. Select *Submit*. - -The submission will be sent via the GitHub API to be registered in an `OSTrails GitHub repository for collecting metadata about these assessment components `_, and indexed by the `FAIRsharing `_ registry. - - -Next steps ----------- - -Once submitted to FAIRsharing, the record will remain hidden until approved by the FAIRsharing curation team. Once made public, claim your record in FAIRsharing. Information on creating an account and claiming a record is available in the next section, and at `fairsharing.gitbook.io `_. - - -FAIRsharing --------------- - -This tutorial provides a comprehensive walkthrough for registering a **Benchmark** directly within the FAIRassist registry on FAIRsharing. - -Prerequisites -------------- -* Ensure you are logged in via your ORCID. This ensures your curation work is publicly attributed to you. You can find out more about creating an account in our `gitbook documentation `_. -* Create a narrative description of your benchmark, and how it interprets the `FAIR Principles `_. You may find the benchmark sections of the tutorial at `define-benchmark-associated-metrics.rst `_ useful. - -Creating a record ------------------- -Please follow the instructions in `our documentation `_ on how to create a new record in FAIRsharing. Once you’ve done that, you will be presented with the more detailed record edit interface. - -Editing your record -------------------- - -Each of the tables below corresponds to a single tab of the edit interface for a FAIRsharing record, and summarises the key fields that should be populated. For complete documentation, see our `gitbook pages `_. - -Remember to save your record regularly. - -General Information --------------------- - -The form in the general information tab establishes the identity, ownership, and scientific scope of your record. - -* `Record Name `_ (Mandatory): Provide the full name of the resource. You should create a name of the format: [[Principle name]] Benchmark - [[descriptive benchmark name]]. An example is “FAIR Benchmark - FAIR Portugal Dataverse Benchmark”. -* `Abbreviation `_ (Optional): You should create an abbreviation of the format: [[Principle abbrev]]B:[[short name for the benchmark]]. An example is “FB - FAIR PT-DV”. -* `Homepage `_ (Mandatory): Provide the homepage URL for the resource. -* `Description `_ (Mandatory): Free-text summary of the resource and its purpose; see also our documentation on descriptions. (Min. 40 chars). -* `Year of creation `_ (Recommended): Provide the year the resource was first released. -* `Contacts `_ (Mandatory): At least one contact point should be provided, consisting of a name and email address for the person or group responsible for the maintenance of the resource. -* `Countries `_ (Mandatory): Select the country or countries where the resource is hosted. At least one must be added. -* `Subjects and Taxonomies `_ (Mandatory): Select the relevant subject area and species. At least one of each must be added. “Not applicable” may be used for the Taxonomy value when the species is irrelevant, as is often the case for benchmarks. -* `Object Type `_ (Mandatory): Define the type of digital research object in scope. At least one object type must be provided for Metrics/Benchmarks. - -Licence and Support Links --------------------------- - -Ensures users understand how to access help and the legal usage rights of the metadata. - -* `Licences `_ (Recommended): Licences for the content of your resource (e.g. the specification) should be listed. Providing licences increases the likelihood of understanding usage rights. -* `Support `_ (Recommended): Support links allow you to supply information about the various types of documentation, training and support available for your resource. - -Publications -------------- - -Connects the record to the literature related to the benchmark. - -* `Publications `_ (Recommended): This section is only for publications that describe your resource and those you would ask others to use when citing your database, standard or policy. -* `Citations `_ (Recommended): You may have one or more publications that should be used to cite your resource. Note this using the 'Cite record using this publication?' toggle. - -Organisations and Grants ------------------------- - -Defines the institutional backing and funding for the resource. - -* `Organisations `_ (Recommended): Each organisation involved should be added with its role. At least one maintaining organisation and one funding organisation should be added. - -Relations to Other Records ----------------------------- - -* `related_to `_ (Recommended): One of the most important parts of a record is its relationships. Link to records (other than metrics) via the autocomplete field using the FAIRsharing ID, full name, or short name. -* `has_associated_metric `_ (Mandatory): Use this relationship to link to every metric implemented by this benchmark. - -Additional Information ------------------------ - -Specific functional metadata for assessment tools. - -* `Associated evaluation tools `_ (Optional): If your metric/benchmark is available from a particular FAIR evaluation tool, please add it here. diff --git a/docs/commons/fair/tutorials/register-metric.rst b/docs/commons/fair/tutorials/register-metric.rst deleted file mode 100644 index e26c023..0000000 --- a/docs/commons/fair/tutorials/register-metric.rst +++ /dev/null @@ -1,229 +0,0 @@ -.. _register-metric: - -How to register a Metric -======================== - -This tutorial explains how to register a **community FAIR Metric** using the OSTrails FAIR Assessment framework. - -A Metric is a narrative description that a Test must wholly implement. Each metric should implement exactly one dimension (e.g. one of the FAIR Principles). They may be domain-agnostic or not. -For more information, check `the FAIR Testing Resource (FTR) vocabulary `_. - -There are two ways to register a Metric. The first is to use the `FAIR Wizard authoring tool `_, a questionnaire-based knowledge model designed to collect and structure metadata for FAIR Assessment Components, including Metrics. It auto-generates FTR specification metadata and stores it within an OSTrails github repository, then registers it in FAIRsharing for you. If you have not yet created FTR files for your metrics, then you should use this option. - -The second is to register your Metric directly with FAIRsharing. If you have already created your FTR specification files for your metrics (eg in your own github repository) then you should use this option. - -This tutorial covers both options. - -Does your metric already exist? -------------------------------- -You should review existing metrics in FAIRsharing for the Principle that you are measuring. If it already exists, then please use that metric in your benchmark rather than creating a new one. To discover the metrics related to a particular Principle, find the Principle in FAIRsharing and explore its relationships. - -For example, if you require a metric for F1 ((Meta)data are assigned globally unique and persistent identifiers) that checks the global uniqueness of an identifier, then visit https://doi.org/10.25504/FAIRsharing.a2cea7 and review the list of related metrics. See also the tutorial on `finding metrics and benchmarks `_. - - -FAIR Wizard ------------- - -.. _metric_prerequisites: - -Prerequisites -------------- - -Before starting you should: - -* Create a narrative description of your metric, and how it interprets the `FAIR Principle `_ that it measures. You may find the metric sections of the tutorial for `defining benchmarks and associated metrics `_ useful. -* Have access to the `FAIR Wizard authoring tool `_. -* Identify the **type of digital object** that your Metric will evaluate. - -.. _create_project: - -Step 1 – Create a Metric project in the FAIR Wizard authoring tool ------------------------------------------------------------------- -1. Go to `the dedicated environment for this questionnaire `_. -2. Register yourself or log in if you already have access. -3. Navigate to Projects and click Create to start a new project. -4. Name your project and use the "**FAIR Assessment Authoring Tool** - Questionnaire for creating FAIR Assessment Components" template as Knowledge Model. -5. Enable **Filter by question tags**. -6. Choose **Metric** as the artefact type. - -By doing this, the tool will create a Metric-tailored questionnaire. - -.. _fill_out_questionnaire: - -Step 2 – Fill in the questionnaire --------------------------------------- - -1. Read the instructions carefully. -2. Work through the form sequentially, completing each section with information relevant to the Metric you are defining. - -Note that there are questions that are *mandatory*, which will be required to be given an answer. Other questions are optional. -The mandatory fields that are required to define a FAIR Metric are: - -- ``Title`` - You should indicate the name of your Metric. To follow OSTrails best practices, consider using this Metric naming scheme: - -[[Principle name]] Metric - [[Abbreviation of sub-principle]] - [[Metadata|Data depending on the focus of the metric]] - [[descriptive metric name]] - -Examples: - - FAIR Metric – F1– Metadata - Persistent identifiers for database content - - FAIR4RS Metric – F1 - Metadata - Software has persistent and unique identifier (https://doi.org/10.25504/FAIRsharing.87c9a8) - -- ``Description`` - You should indicate a description of your Metric. - -- ``Abbreviation`` - You should indicate a single-word abbreviation for your Metric. Note that FAIR Wizard does not allow the use of spaces or any of these special characters in Benchmark/Metric/Test name abbreviations: : / ? # [ ] @ ! $ & ' ( ) * + , ; = "< > \ ^ { < > : " / \ - -To follow OSTrails best practices, consider using this Metric naming scheme: - -[[Principle abbrev]]M_[[Abbreviation of sub-principle]]_[[M|D|P]]_[[short name for the metric]] - -Examples: - - FM_F1-PID_M_ARK - - FSM_F1_M_UNIQ-ID - - FM_R1.2_M_CPI - -- ``License`` - You should include a license URL for this Metric. - -- ``Version`` - You should indicate the version number you are interested in using for defining your Metric. - -- ``Responsable contact person`` - You should provide the name and email of a responsible contact person. You will find an ORCID-integrated browser to search for your personal information by either typing in your full name or your ORCID ID directly. - -- ``Country`` - You should indicate the country or geographical scope relevant to this Metric. If the Metric is not limited to a specific region, you can select *’Worldwide’*. - -- ``Subject`` - You should specify the application domain or area of knowledge to which the Metric applies. If the Metric is intended to be domain-independent, you can select *’Subject Agnostic’*. - -- ``Object type`` - You should indicate the type of digital object that the Metric evaluates (for example datasets, software, or workflows). If the Metric applies broadly, you can select Object type *’Agnostic’*. - -- ``Taxonomy`` - You should classify the Metric within a taxonomy. If no suitable classification is available or needed, you can select *’Not Applicable’*. - -- ``Link to a principle`` - You should link the Metric to at least one FAIR Principle. This defines which aspect of FAIRness the Metric evaluates and is essential for its interpretation and reuse. - - -**Please complete all optional sections that it is possible for you to complete. The more complete your metric, the more re-usable and FAIR it is. Incomplete metadata may delay the publishing of your Metric in FAIRsharing.** - - -Step 3 – Create an instance with your answers ---------------------------------------------- - -Once the questionnaire has been completed: - -1. Go to the **Documents** section in the top menu. -2. Name your document and select the latest version of the "*FAIR Assessment Authoring Tool* - Jinja2-based template for authoring and registering FAIR Assessment Components" as Document Template. -3. Choose the "Metric / Benchmark" Format option. -4. Click on *Create*. - -This will create a JSON file with your input. - -Step 4 – Submit your document --------------------------------------- - -Now, you can review the document with your answers to the questionnaire, by clicking on it, which will initiate the download of the file. Once you're happy with it, you're ready to submit your document: - -4. In the **Documents** section, click the three dots icon (⋯) beside your document. -5. Select *Submit*. - -The submission will be sent via the GitHub API to be registered in an `OSTrails GitHub repository for collecting metadata about these assessment components `_, and indexed by the `FAIRsharing `_ registry. - - -Next steps ----------- - -Once submitted to FAIRsharing, the record will remain hidden until approved by the FAIRsharing curation team. Once made public, claim your record in FAIRsharing. Information on creating an account and claiming a record is available in the next section, and at https://fairsharing.gitbook.io/ - - -FAIRsharing ------------ - -This tutorial provides a comprehensive walkthrough for registering a **Metric** directly within the FAIRassist registry on FAIRsharing. - -.. _fs_prerequisites: - -Prerequisites -------------- -* Ensure you are logged in via your ORCID. This ensures your curation work is publicly attributed to you. You can find out more about creating an account in our `gitbook documentation `_. -* Create a narrative description of your metric, and how it interprets the `FAIR Principle `_ that it measures. You may find the metric sections of the tutorial at `define-benchmark-associated-metrics.rst `_ useful. - -Creating a record ------------------ -Please follow the instructions in `our documentation `_ on how to create a new record in FAIRsharing. Once you’ve done that, you will be presented with the more detailed record edit interface. - -Editing your record -------------------- - -Each of the tables below corresponds to a single tab of the edit interface for a FAIRsharing record, and summarises the key fields that should be populated. For complete documentation, see our `gitbook pages `_. - -Remember to save your updates regularly. - -General Information ------------------------ - -The form in the general information tab establishes the identity, ownership, and scientific scope of your record. - -General Information --------------------- - -The form in the general information tab establishes the identity, ownership, and scientific scope of your record. - -* `Record Name `_ (Mandatory): Provide the full name of the resource. You should create a name of the format: [[Principle name]] Metric - [[Abbreviation of sub-principle]] - [[Metadata or Data]] [[descriptive metric name]]. An example is “FAIR Metric – F1 – Metadata - Identifier is globally unique”. -* `Abbreviation `_ (Optional): You should create an abbreviation of the format: [[Principle abbrev]]M:[[Abbreviation of sub-principle]]:[[M or D]]:[[short name for the metric]]. An example is “FM:F1:M:IdentUnique”. -* `Homepage `_ (Mandatory): Provide the homepage URL for the resource. -* `Description `_ (Mandatory): Free-text summary of the resource and its purpose; see also our documentation on descriptions. (Min. 40 chars). -* `Year of creation `_ (Recommended): Provide the year the resource was first released. -* `Contacts `_ (Mandatory): At least one contact point should be provided, consisting of a name and email address for the person or group responsible for the maintenance of the resource. -* `Countries `_ (Mandatory): Select the country or countries where the resource is hosted. At least one must be added. -* `Subjects and Taxonomies `_ (Mandatory): Select the relevant subject area and species. At least one of each must be added. “Not applicable” may be used for the Taxonomy value when the species is irrelevant, as is often the case for metrics. -* `Object Type `_ (Mandatory): Define the type of digital research object in scope. At least one object type must be provided for Metrics/Benchmarks. - -Licence and Support Links -------------------------- - -Ensures users understand how to access help and the legal usage rights of the metadata. - -* `Licences `_ (Recommended): Licences for the content of your resource (e.g. the specification) should be listed. Providing licences increases the likelihood of understanding usage rights. -* `Support `_ (Recommended): Support links allow you to supply information about the various types of documentation, training and support available for your resource. - -Publications -------------- - -Connects the record to the literature related to the metric. - -* `Publications `_ (Recommended): This section is only for publications that describe your resource and those you would ask others to use when citing your database, standard or policy. -* `Citations `_ (Recommended): You may have one or more publications that should be used to cite your resource. Note this using the 'Cite record using this publication?' toggle. - -Organisations and Grants ------------------------- - -Defines the institutional backing and funding for the resource. - -* `Organisations `_ (Recommended): Each organisation involved should be added with its role. At least one maintaining organisation and one funding organisation should be added. - -Relations to Other Records ----------------------------- - -* `related_to `_ (Recommended): One of the most important parts of a record is its relationships. Link to records (other than benchmarks) via the autocomplete field using the FAIRsharing ID, full name, or short name. -* `measures_principle `_ (Mandatory): Every metric must be linked to exactly ONE principle record from any given principle hierarchy. Use for the narrowest principle possible (e.g. FAIR F1). Cannot point to two principles from the same hierarchy. - -Additional Information ------------------------ - -Specific functional metadata for assessment tools. - -* `Associated evaluation tools `_ (Optional): If your metric/benchmark is available from a particular FAIR evaluation tool, please add it here. -* `Associated Tests `_ (Optional): Links to the tests that execute this metric. -* `Positive, Negative and Indeterminate examples `_ (Optional): URLs that provide illustrative examples of positive, negative and indeterminate outcomes. - - diff --git a/docs/commons/fair/tutorials/run-existing-test.rst b/docs/commons/fair/tutorials/run-existing-test.rst deleted file mode 100644 index 98a60ee..0000000 --- a/docs/commons/fair/tutorials/run-existing-test.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _run-existing-test: - -How to run an existing Test -============================== - -Using the FAIR Champion GUI: - -https://tools.ostrails.eu/champion/tests/ - -1. Search (using the browser text search) for the test you want to execute. -2. Click "Execute Text" - this will trigger the creation of a form appropriate for that test -3. Fill-in the form field(s) -4. Click "Run Test" - -Alternatively, if you want to automate many executions, you can: - -1. a. Use the GUI to find the test (e.g. "fc_data_identifier_in_metadata") -2. a. Right-click on the blue test title and "copy Link" (this is necessary because clicking the link might follow a content-negotiated path to a nice web page, rather than giving you the identifier of the test!) - -OR - -1. b. Use FAIRSharing to find the Metric that interests you -2. b. Identify a test on the FAIRSharing page that implements that Metric - -3. Prepare your input, in the format: { "resource_identifier": "GUID" } -4. use the code example in the top of that Web page, together with your Test identifier and your input - - curl -H "Content-type: application/json" -H "Accept: application/json" - -d '{"resource_identifier": "https://exampledataset.org"}' - https://tests.ostrails.eu/tests/fc_data_identifier_in_metadata - diff --git a/docs/commons/fair/tutorials/tutorial-index.rst b/docs/commons/fair/tutorials/tutorial-index.rst deleted file mode 100644 index 1ed1905..0000000 --- a/docs/commons/fair/tutorials/tutorial-index.rst +++ /dev/null @@ -1,23 +0,0 @@ -Tutorials for FTR implementation -================================== - -Documenattion that explain how implement different workflows for the FTR. - -The following list in this section are part of the tutorials documentation. - -.. toctree:: - :caption: Tutorials - :maxdepth: 1 - :titlesonly: - - How to define a FAIR Benchmark with its associated Metrics - How to find metrics and benchmarks - How to find a Test appropriate for my digital object - How to run an existing Test - How to deploy Champion myself - How to define and run a scoring algorithm - How to register a benchmark - How to register a metric - How to Create and Register a Test following the FTR API - How host/deploy a test - As a fair assessment developer, how comply to FTR spec diff --git a/docs/index.rst b/docs/index.rst index 7ed929e..06fa33f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -32,12 +32,6 @@ The documentation is structured as follows: SKG Commons FAIR Commons -.. toctree:: - :maxdepth: 4 - :caption: Toolbox of Testing Services - - Toolbox of Testing Services - .. toctree:: :maxdepth: 4 diff --git a/docs/tools/authoring-and-registering/ostrails-index.rst b/docs/tools/authoring-and-registering/ostrails-index.rst deleted file mode 100644 index 5e987d8..0000000 --- a/docs/tools/authoring-and-registering/ostrails-index.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. _software-registry: - -OSTrails Software Tools Index -============================= - -The OSTrails Software Tools Index provides a curated list of -software tools that support the creation, registration, and -evaluation of FAIR digital objects. - -It is not (primarily) intended to be used by humans, but rather by software -agents that can query the index and retrieve information about the -tools and their capabilities. Other tools, such as the Component -Authoring Tool, speak directy to the index to retrieve information about the available tests or algorithms, -or can write new information to the index about newly created tests or -algorithms. The index is also used by the FAIR Validator to retrieve information about the available tests and their associated metrics and benchmarks. - -.. raw:: html - - The homepage of the OSTrails Software Tools Index is available at: - - OSTrails Software Registry. diff --git a/docs/tools/authoring.rst b/docs/tools/authoring.rst deleted file mode 100644 index a807b0f..0000000 --- a/docs/tools/authoring.rst +++ /dev/null @@ -1,16 +0,0 @@ -OSTrails FAIR Tools -==================== - - -The following resources in this section are part of the FAIR Tools component. - -.. toctree:: - :caption: Authoring and Registration Tools - :maxdepth: 1 - :titlesonly: - - FAIRassist (Conceptual Component Registry) - Assessment Component Authoring Tool - FAIR Validator - OSTrails Software Tools Registry - diff --git a/docs/tools/dmp.rst b/docs/tools/dmp.rst index 6a696f2..d17a8e3 100644 --- a/docs/tools/dmp.rst +++ b/docs/tools/dmp.rst @@ -1,16 +1,9 @@ OSTrails DMP Tools =================== - DAMAP, DSWizard, and Argos are Data Management Plan (DMP) platforms that work towards implementing the DMP Common Standard (DMP-IF). These tools adopt and use the common concepts, structures, and conventions described in this documentation to enable interoperability and exchange of DMP information. For tool-specific functionality, implementation details, or support related to DMP-IF, please contact the respective tool providers directly. - -.. toctree:: - :caption: DMP Tools - :maxdepth: 1 - :titlesonly: - - DAMAP - DSWizard - Argos + - DAMAP: https://damap.org/ + - DSWizard: https://ds-wizard.org/ + - Argos: https://argos.openaire.eu/portal/ diff --git a/docs/tools/fair-assessment.rst b/docs/tools/fair-assessment.rst deleted file mode 100644 index 2d28ca4..0000000 --- a/docs/tools/fair-assessment.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. _tool-fair-assessment: - -OSTrails FAIR Tools -==================== - - -The following resources in this section are part of the FAIR Tools component. - -.. toctree:: - :caption: Assesment Platforms - :maxdepth: 1 - :titlesonly: - - FAIR Champion - FOOPS - FAIROS - RSFC - diff --git a/docs/tools/fair.rst b/docs/tools/fair.rst index 3111b8a..142ce79 100644 --- a/docs/tools/fair.rst +++ b/docs/tools/fair.rst @@ -5,16 +5,15 @@ OSTrails FAIR Tools The following resources in this section are part of the FAIR Tools component. .. toctree:: - :caption: All FAIR Tools + :caption: Tools :maxdepth: 1 :titlesonly: - FAIR Champion - FOOPS - FAIROS - RSFC - FAIRassist (Conceptual Component Registry) - Assessment Component Authoring Tool - FAIR Validator - OSTrails Software Tools Index + FAIR Champion + FOOPS + FAIROS + FAIRsharing + FAIR Assessment Authoring Tool + FAIR Validator + RSFC diff --git a/docs/tools/authoring-and-registering/fair-assessment-authoring-tool.rst b/docs/tools/fair/fair-assessment-authoring-tool.rst similarity index 100% rename from docs/tools/authoring-and-registering/fair-assessment-authoring-tool.rst rename to docs/tools/fair/fair-assessment-authoring-tool.rst diff --git a/docs/tools/assessment/fair-champion.rst b/docs/tools/fair/fair-champion.rst similarity index 100% rename from docs/tools/assessment/fair-champion.rst rename to docs/tools/fair/fair-champion.rst diff --git a/docs/tools/quality-control/fair-validator.rst b/docs/tools/fair/fair-validator.rst similarity index 100% rename from docs/tools/quality-control/fair-validator.rst rename to docs/tools/fair/fair-validator.rst diff --git a/docs/tools/assessment/fairos.rst b/docs/tools/fair/fairos.rst similarity index 97% rename from docs/tools/assessment/fairos.rst rename to docs/tools/fair/fairos.rst index b656eb6..957d024 100644 --- a/docs/tools/assessment/fairos.rst +++ b/docs/tools/fair/fairos.rst @@ -1,6 +1,3 @@ - -.. _tool-fairos: - FAIROS ^^^^^^ diff --git a/docs/tools/authoring-and-registering/fairassist.rst b/docs/tools/fair/fairsharing.rst similarity index 100% rename from docs/tools/authoring-and-registering/fairassist.rst rename to docs/tools/fair/fairsharing.rst diff --git a/docs/tools/assessment/foops.rst b/docs/tools/fair/foops.rst similarity index 100% rename from docs/tools/assessment/foops.rst rename to docs/tools/fair/foops.rst diff --git a/docs/tools/assessment/rsfc.rst b/docs/tools/fair/rsfc.rst similarity index 100% rename from docs/tools/assessment/rsfc.rst rename to docs/tools/fair/rsfc.rst diff --git a/docs/tools/quality-control.rst b/docs/tools/quality-control.rst deleted file mode 100644 index 84f81ab..0000000 --- a/docs/tools/quality-control.rst +++ /dev/null @@ -1,13 +0,0 @@ -OSTrails FAIR Tools -==================== - - -The following resources in this section are part of the FAIR Tools component. - -.. toctree:: - :caption: Tools - :maxdepth: 1 - :titlesonly: - - FAIR Validator - diff --git a/docs/tools/toolbox.rst b/docs/tools/toolbox.rst deleted file mode 100644 index 38a2339..0000000 --- a/docs/tools/toolbox.rst +++ /dev/null @@ -1,42 +0,0 @@ -OSTrails DELIVERABLE 3.2: Toolbox of Testing Services -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The OSTrails Interoperability Framework defines a variety of digital objects that represent -the conceptual and code-level artefacts in the assessment space. At the conceptual level -are Metrics and Benchmarks. At the code level are Tests and Algorithms. - -It is also important to distinguish between the code of a service and its deployment as an active endpoint. -Generally speaking, DMP tests are provided as code-level objects in the project GitHub and do not -exist as public services. In the case of FAIR tests, these have been adopted by a commercial entity -and will be updated and maintained as active endpoints beyond the end of the OSTrails project. As such, -the lists of Tests below differs slightly between the DMP Tests (code) and the FAIR Tests (active endpoints). -Both FAIR tests and DMP tests are compliant with the FTR Vocabulary, and are thus interoperable. - -.. toctree:: - :caption: Toolbox - :maxdepth: 1 - :titlesonly: - - FAIR Metrics - DMP Metrics - FAIR Tests - DMP Tests - FAIR Benchmarks - FAIR Algorithms - FAIR Testing Platforms - DMP Assessment Tools - SKG Tools - -In addition to testing and assessment tools, -the OSTrails project has also developed a number of other tools -that support the testing ecosystem. -These include: - - -.. toctree:: - :caption: Supporting Tools - :maxdepth: 1 - :titlesonly: - - Assessment Authoring and Registration Tools - Validation and Quality Control Tools diff --git a/docs/tools/toolbox/dmp-metrics.rst b/docs/tools/toolbox/dmp-metrics.rst deleted file mode 100644 index 8b8d249..0000000 --- a/docs/tools/toolbox/dmp-metrics.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. _tool-dmp-metrics: - -DMP Metrics -^^^^^^^^^^^ -.. raw:: html - - Open the catalogue of DMP Metrics - diff --git a/docs/tools/toolbox/dmp-tests.rst b/docs/tools/toolbox/dmp-tests.rst deleted file mode 100644 index 5d6ca28..0000000 --- a/docs/tools/toolbox/dmp-tests.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. _tool-dmp-tests: - -DMP Tests -^^^^^^^^^^ -.. raw:: html - - Open the catalogue of DMP Tests - diff --git a/docs/tools/toolbox/fair-algorithms.rst b/docs/tools/toolbox/fair-algorithms.rst deleted file mode 100644 index 209ad9f..0000000 --- a/docs/tools/toolbox/fair-algorithms.rst +++ /dev/null @@ -1,138 +0,0 @@ - -.. _tool-fair-algorithms: - -FAIR Algorithms -^^^^^^^^^^^^^^^ - -The Algorithms below are maintained as live endpoints by the OSTrails project and catalogued in the OSTrails testing infrastructure. -All Algorithms are compliant with the `FTR Vocabulary `_ - -Use the search box to filter by Algorithm name or description. - -.. raw:: html - - - - -
-
Loading FAIR Algorithms catalogue…
- - diff --git a/docs/tools/toolbox/fair-benchmarks.rst b/docs/tools/toolbox/fair-benchmarks.rst deleted file mode 100644 index 08a963e..0000000 --- a/docs/tools/toolbox/fair-benchmarks.rst +++ /dev/null @@ -1,10 +0,0 @@ - -.. _tool-fair-benchmarks: - -FAIR Benchmarks -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. raw:: html - - The Community-authored Benchmarks for FAIR assessment are - catalogued in the FAIR Assist repository (hosted by FAIRSharing). diff --git a/docs/tools/toolbox/fair-metrics.rst b/docs/tools/toolbox/fair-metrics.rst deleted file mode 100644 index e4dcf5c..0000000 --- a/docs/tools/toolbox/fair-metrics.rst +++ /dev/null @@ -1,8 +0,0 @@ - -.. _tool-fair-metrics: - -FAIR Metrics -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. raw:: html - - The Metrics for FAIR Testing are catalogued in the FAIR Assist repository (hosted by FAIRSharing). diff --git a/docs/tools/toolbox/fair-tests.rst b/docs/tools/toolbox/fair-tests.rst deleted file mode 100644 index 8fff4b6..0000000 --- a/docs/tools/toolbox/fair-tests.rst +++ /dev/null @@ -1,139 +0,0 @@ - -.. _tool-fair-tests: - -FAIR Tests -^^^^^^^^^^ - -The tests below are maintained as live endpoints by the OSTrails project and catalogued in the OSTrails testing infrastructure. -All tests are compliant with the `FTR Vocabulary `_ and can be executed through the platforms described in :ref:`here ` - - -Use the search box to filter by test name or description. - -.. raw:: html - - - - -
-
Loading FAIR test catalogue…
- -