From e95d3f5b4a2e7005db1b3c88f26f22f1b59a5d23 Mon Sep 17 00:00:00 2001 From: Stephen Von Worley Date: Fri, 21 Aug 2026 09:17:31 -0700 Subject: [PATCH 1/6] first draft --- docs/_attic/glossary_entries.py | 22 ++++-- docs/_attic/glossary_entries_list_dynamic.txt | 1 + docs/end-user-topics/categories.rst | 71 +++++++++++++++++++ docs/index.rst | 1 + 4 files changed, 88 insertions(+), 7 deletions(-) create mode 100644 docs/end-user-topics/categories.rst diff --git a/docs/_attic/glossary_entries.py b/docs/_attic/glossary_entries.py index ffca98ec..e0d19e2a 100644 --- a/docs/_attic/glossary_entries.py +++ b/docs/_attic/glossary_entries.py @@ -100,12 +100,13 @@ institute="", pronunciation='') -Catagories = GlossEntry("categories", - acronym_full="", - definition="A group of workflows or tools curated by Dockstore with a similar scientific purpose.", - furtherreading="", - institute="", - pronunciation='') +Catagories = GlossEntry("categories", + acronym_full="", + definition="A grouping of Dockstore entries that share the same trait. They might relate to the same scientific topic, perform the same operation, read/write the same data type or format, etc.", + furtherreading="", + institute="", + pronunciation='', + seealso="[EDAM]") Collections = GlossEntry("collection", acronym_full="", @@ -233,7 +234,14 @@ institute="", pronunciation='') -Egress = GlossEntry("egress", +EDAM = GlossEntry("EDAM", + acronym_full="", + definition="An ontology of terms for bioinformatics, covering operations, types of data, data formats, and topics. Dockstore's [categories] system is based on EDAM, bolstered with additional AI-suggested categories not present in the ontology.", + furtherreading="https://edamontology.org/", + institute="", + pronunciation='') + +Egress = GlossEntry("egress", acronym_full="", definition="The action of leaving a place. In the context of [cloud computing], data egress refers to data being moved from one location to another, such as from the cloud to a local machine, between cloud providers, and between locations of a single cloud provider. Data egress often results in the charge of fees (usually called egress charges). Data egress can be one of the most expensive cloud costs incurred. Sometimes, the person hosting the file is charged for data egress. Other times, the person downloading the file is charged (such as when downloading files from a Google bucket that has the requester-pays option enabled).", furtherreading="", diff --git a/docs/_attic/glossary_entries_list_dynamic.txt b/docs/_attic/glossary_entries_list_dynamic.txt index 8213c037..95130534 100644 --- a/docs/_attic/glossary_entries_list_dynamic.txt +++ b/docs/_attic/glossary_entries_list_dynamic.txt @@ -32,6 +32,7 @@ DOI DRS DS-I Africa EC2 +EDAM egress eLwazi entry diff --git a/docs/end-user-topics/categories.rst b/docs/end-user-topics/categories.rst new file mode 100644 index 00000000..3ebc5f05 --- /dev/null +++ b/docs/end-user-topics/categories.rst @@ -0,0 +1,71 @@ +Categories +========== + +A :ref:`dict categories` is a grouping of Dockstore entries (tools, workflows, and notebooks) that +share the same trait. Entries in a category might relate to the same scientific topic, perform the +same operation, or read/write the same type or format of data. Categories help users discover +entries that are similar to ones they already know about, and let you filter search results down to +entries relevant to a particular area of interest. + +An entry can belong to any number of categories, and categories are shown as small labelled +"bubbles" wherever an entry is displayed. + +Dockstore-Curated and AI-Curated Categories +-------------------------------------------- + +Categories come from two sources: + +* **Dockstore-curated categories** are created and populated by hand by a Dockstore curator. A + curator defines the category and manually adds the entries that belong to it. +* **AI-curated categories** are assigned automatically. Dockstore uses an in-house AI to analyze an + entry's name, description, and files, and classify the entry into the categories it best matches. + +AI-curated category bubbles are shown with a grey tint to distinguish them from Dockstore-curated +ones. Hovering over a category bubble shows a tooltip explaining how the category was created, and, +for AI-curated categories, how the entry was placed into it. + +.. note:: + Dockstore's use of AI to curate categories follows our :ref:`what-is-dockstore-generative-ai-policy`. + Only already-public entry information is used, and entry owners can review and correct the AI's + classifications, as described below. + +EDAM and Our Extensions +------------------------ + +The AI-curated categories are based on `EDAM `__, a bioinformatics +ontology that organizes terms describing operations, data, formats, and topics. Dockstore bolsters +EDAM with additional categories, suggested by AI, for concepts that are not present in the ontology. + +AI-curated categories are organized into six sets, corresponding to the branches of EDAM that +Dockstore draws on: + +* **Operation** -- the analytical operation(s) an entry performs +* **Topic** -- the scientific topic or field an entry relates to +* **Input data** -- the type(s) of data an entry consumes +* **Input format** -- the file format(s) an entry consumes +* **Output data** -- the type(s) of data an entry produces +* **Output format** -- the file format(s) an entry produces + +.. note:: + The "topic" category set is unrelated to an entry's :ref:`dict topic`, which is a short, + free-text description of the entry set in :ref:`dict .dockstore.yml` or the Dockstore UI. + +How Categories Are Displayed +----------------------------- + +Categories that an entry belongs to are shown as bubbles on the entry's public page. They also +appear alongside entries in search results, where you can use the category facets to filter results +down to entries that belong to one or more particular categories, the same way you would filter by +any other :doc:`search facet `. + +How Entry Owners Can Curate Categories +---------------------------------------- + +Entry owners can review the AI's category assignments for their own entries. From an entry's private +page, click ``Manage Categories`` to see the categories the AI has proposed and approve or reject the +entry's membership in each one. Rejecting a category removes its bubble from the entry's public page +and search results; approving it confirms the assignment. + +Dockstore-curated categories are managed by Dockstore curators rather than entry owners. If you think +an entry should be added to (or removed from) a Dockstore-curated category, reach out to the +Dockstore team, for example via `Discourse `__. diff --git a/docs/index.rst b/docs/index.rst index 3fde10e9..3cf58c93 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -172,6 +172,7 @@ Notebook Environments :maxdepth: 1 end-user-topics/end-user-topics + end-user-topics/categories end-user-topics/faceted-search end-user-topics/starring end-user-topics/language-support From a06237af89ded5d56a0cb5b1581f6c58eee88979 Mon Sep 17 00:00:00 2001 From: Stephen Von Worley Date: Fri, 21 Aug 2026 10:48:21 -0700 Subject: [PATCH 2/6] human edits --- docs/_attic/glossary_entries.py | 4 +- docs/_attic/glossary_entries_list_dynamic.txt | 2 +- docs/end-user-topics/categories.rst | 78 +++++++++---------- 3 files changed, 42 insertions(+), 42 deletions(-) diff --git a/docs/_attic/glossary_entries.py b/docs/_attic/glossary_entries.py index e0d19e2a..cac0b593 100644 --- a/docs/_attic/glossary_entries.py +++ b/docs/_attic/glossary_entries.py @@ -100,7 +100,7 @@ institute="", pronunciation='') -Catagories = GlossEntry("categories", +Catagories = GlossEntry("category", acronym_full="", definition="A grouping of Dockstore entries that share the same trait. They might relate to the same scientific topic, perform the same operation, read/write the same data type or format, etc.", furtherreading="", @@ -236,7 +236,7 @@ EDAM = GlossEntry("EDAM", acronym_full="", - definition="An ontology of terms for bioinformatics, covering operations, types of data, data formats, and topics. Dockstore's [categories] system is based on EDAM, bolstered with additional AI-suggested categories not present in the ontology.", + definition="An ontology of bioinformatics concepts, covering operations, topics, and data formats and types. Dockstore derives its AI-curated [category] structure from EDAM, which it enhances with additional AI-suggested categories not present in the original ontology.", furtherreading="https://edamontology.org/", institute="", pronunciation='') diff --git a/docs/_attic/glossary_entries_list_dynamic.txt b/docs/_attic/glossary_entries_list_dynamic.txt index 95130534..2df6104d 100644 --- a/docs/_attic/glossary_entries_list_dynamic.txt +++ b/docs/_attic/glossary_entries_list_dynamic.txt @@ -10,7 +10,7 @@ BD Catalyst BDC BioData Catalyst Cancer Genomics Cloud -categories +category CGC CLI cloud computing diff --git a/docs/end-user-topics/categories.rst b/docs/end-user-topics/categories.rst index 3ebc5f05..fcae5376 100644 --- a/docs/end-user-topics/categories.rst +++ b/docs/end-user-topics/categories.rst @@ -1,71 +1,71 @@ Categories ========== -A :ref:`dict categories` is a grouping of Dockstore entries (tools, workflows, and notebooks) that +A :ref:`dict category` is a grouping of Dockstore entries (tools, workflows, and notebooks) that share the same trait. Entries in a category might relate to the same scientific topic, perform the -same operation, or read/write the same type or format of data. Categories help users discover -entries that are similar to ones they already know about, and let you filter search results down to -entries relevant to a particular area of interest. +same operation, or read/write the same type or format of data. -An entry can belong to any number of categories, and categories are shown as small labelled -"bubbles" wherever an entry is displayed. +Dockstore places entries into categories to help users to better +understand the entries, find entries relevant to a particular area of interest, +and discover entries that are similar to those they already know about. -Dockstore-Curated and AI-Curated Categories --------------------------------------------- +An entry can belong to any number of categories. + +How Categories Are Displayed +----------------------------- + +In the Dockstore UI, the categories that an entry belongs to are shown as small "bubbles" that are labelled with the category name. These appear on entry's page, +and also in search results, where you can use the category-related search facets to filter results +by one or more particular categories, in the same way you would filter using any other :doc:`search facet `. + +AI and Dockstore-Curated Categories +----------------------------------- Categories come from two sources: +* **AI-curated categories** are derived from the `EDAM `__ ontology. Dockstore populates these categories automatically, using an AI model to + analyze each entry's name, description, and files, and classify the entry into the categories that + it best matches. * **Dockstore-curated categories** are created and populated by hand by a Dockstore curator. A curator defines the category and manually adds the entries that belong to it. -* **AI-curated categories** are assigned automatically. Dockstore uses an in-house AI to analyze an - entry's name, description, and files, and classify the entry into the categories it best matches. AI-curated category bubbles are shown with a grey tint to distinguish them from Dockstore-curated -ones. Hovering over a category bubble shows a tooltip explaining how the category was created, and, -for AI-curated categories, how the entry was placed into it. +ones. Hovering over a category bubble shows a tooltip that explains how the category was created +and how the entry was placed into it. .. note:: - Dockstore's use of AI to curate categories follows our :ref:`what-is-dockstore-generative-ai-policy`. + Dockstore's use of AI to curate categories follows our :ref:`approach to AI `. Only already-public entry information is used, and entry owners can review and correct the AI's classifications, as described below. EDAM and Our Extensions ------------------------ -The AI-curated categories are based on `EDAM `__, a bioinformatics -ontology that organizes terms describing operations, data, formats, and topics. Dockstore bolsters -EDAM with additional categories, suggested by AI, for concepts that are not present in the ontology. +Dockstore derives its AI-curated categories from `EDAM `__, a bioinformatics +ontology that organizes concepts by operation, topic, data type, and data format. To improve coverage, Dockstore includes +additional AI-suggested categories not found in the original EDAM ontology. -AI-curated categories are organized into six sets, corresponding to the branches of EDAM that -Dockstore draws on: +The AI-curated categories are organized into six sets, each corresponding to a subontology of EDAM: -* **Operation** -- the analytical operation(s) an entry performs -* **Topic** -- the scientific topic or field an entry relates to -* **Input data** -- the type(s) of data an entry consumes -* **Input format** -- the file format(s) an entry consumes -* **Output data** -- the type(s) of data an entry produces -* **Output format** -- the file format(s) an entry produces +* **Operation**: operations an entry performs +* **Topic**: scientific subject or field an entry relates to +* **Input Format**: file formats an entry consumes +* **Input Data**: types of data an entry consumes +* **Output Format**: file formats an entry produces +* **Output Data**: types of data an entry produces .. note:: The "topic" category set is unrelated to an entry's :ref:`dict topic`, which is a short, free-text description of the entry set in :ref:`dict .dockstore.yml` or the Dockstore UI. -How Categories Are Displayed ------------------------------ - -Categories that an entry belongs to are shown as bubbles on the entry's public page. They also -appear alongside entries in search results, where you can use the category facets to filter results -down to entries that belong to one or more particular categories, the same way you would filter by -any other :doc:`search facet `. - -How Entry Owners Can Curate Categories ----------------------------------------- +Entry Owners Can Curate the AI +------------------------------ -Entry owners can review the AI's category assignments for their own entries. From an entry's private -page, click ``Manage Categories`` to see the categories the AI has proposed and approve or reject the -entry's membership in each one. Rejecting a category removes its bubble from the entry's public page -and search results; approving it confirms the assignment. +Entry owners can review the AI categorizations of their own entries. On an entry's private +page, click ``Manage Categories`` to view the entry's categories and approve or reject each AI-curated membership. +**Approving** confirms the membership and marks it as approved by the owner. +**Rejecting** permanently removes the entry from the category. -Dockstore-curated categories are managed by Dockstore curators rather than entry owners. If you think +Dockstore-curated categories are managed exclusively by Dockstore curators. If you think an entry should be added to (or removed from) a Dockstore-curated category, reach out to the Dockstore team, for example via `Discourse `__. From bd8ce606138c04084ebad9aac94a179fe4c61598 Mon Sep 17 00:00:00 2001 From: Stephen Von Worley Date: Mon, 24 Aug 2026 10:54:03 -0700 Subject: [PATCH 3/6] fix link to gitlab container registry --- docs/getting-started/getting-started-with-docker.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/getting-started-with-docker.rst b/docs/getting-started/getting-started-with-docker.rst index cfbbf671..17af52a5 100644 --- a/docs/getting-started/getting-started-with-docker.rst +++ b/docs/getting-started/getting-started-with-docker.rst @@ -46,7 +46,7 @@ Sometimes, the tool you want to run is already Dockerized. Perhaps you want to u Container registries ~~~~~~~~~~~~~~~~~~~~ -Docker images are usually shared on registries. `Quay.io `__ and `Docker Hub `__ are examples of popular public registries, which anyone can browse online. `GitLab Container Registry `__ on the other hand is a private registry, so it can't be easily browsed by outside users. +Docker images are usually shared on registries. `Quay.io `__ and `Docker Hub `__ are examples of popular public registries, which anyone can browse online. `GitLab Container Registry `__ on the other hand is a private registry, so it can't be easily browsed by outside users. Container registries usually show you the layers that make up a particular Docker image, what versions are available, and the username or organization that the Docker image is associated with. They also usually give you the command line text you need to use in order to download a particular image locally, which will allow you use to the image on your own machine. From f23d0c26f5bf0e293c358cf35de0072834722a96 Mon Sep 17 00:00:00 2001 From: Stephen Von Worley Date: Mon, 24 Aug 2026 11:30:16 -0700 Subject: [PATCH 4/6] edit and remove extra space --- docs/_attic/glossary_entries.py | 2 +- docs/end-user-topics/categories.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/_attic/glossary_entries.py b/docs/_attic/glossary_entries.py index cac0b593..188238df 100644 --- a/docs/_attic/glossary_entries.py +++ b/docs/_attic/glossary_entries.py @@ -236,7 +236,7 @@ EDAM = GlossEntry("EDAM", acronym_full="", - definition="An ontology of bioinformatics concepts, covering operations, topics, and data formats and types. Dockstore derives its AI-curated [category] structure from EDAM, which it enhances with additional AI-suggested categories not present in the original ontology.", + definition="An ontology of bioinformatics concepts, covering operations, topics, formats, and data types. Dockstore derives its AI-curated [category] structure from EDAM, which it enhances with additional AI-suggested categories not present in the original ontology.", furtherreading="https://edamontology.org/", institute="", pronunciation='') diff --git a/docs/end-user-topics/categories.rst b/docs/end-user-topics/categories.rst index fcae5376..97e38bcf 100644 --- a/docs/end-user-topics/categories.rst +++ b/docs/end-user-topics/categories.rst @@ -5,7 +5,7 @@ A :ref:`dict category` is a grouping of Dockstore entries (tools, workflows, and share the same trait. Entries in a category might relate to the same scientific topic, perform the same operation, or read/write the same type or format of data. -Dockstore places entries into categories to help users to better +Dockstore places entries into categories to help users to better understand the entries, find entries relevant to a particular area of interest, and discover entries that are similar to those they already know about. From 80502b58731882576058357606014e26a05124ba Mon Sep 17 00:00:00 2001 From: Stephen Von Worley Date: Wed, 26 Aug 2026 09:45:13 -0700 Subject: [PATCH 5/6] apply review feedback --- docs/_attic/glossary_entries.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_attic/glossary_entries.py b/docs/_attic/glossary_entries.py index 188238df..ac64fd66 100644 --- a/docs/_attic/glossary_entries.py +++ b/docs/_attic/glossary_entries.py @@ -102,7 +102,7 @@ Catagories = GlossEntry("category", acronym_full="", - definition="A grouping of Dockstore entries that share the same trait. They might relate to the same scientific topic, perform the same operation, read/write the same data type or format, etc.", + definition="A grouping of Dockstore entries that share the same trait. They might relate to the same scientific topic, perform the same operation, input/output the same type of data or format, etc.", furtherreading="", institute="", pronunciation='', From db3035be4b29b9ab6d14f910b0fe3d70bc65af90 Mon Sep 17 00:00:00 2001 From: Stephen Von Worley Date: Wed, 26 Aug 2026 10:06:36 -0700 Subject: [PATCH 6/6] add discourse link manually --- docs/end-user-topics/categories.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/end-user-topics/categories.rst b/docs/end-user-topics/categories.rst index 97e38bcf..14276129 100644 --- a/docs/end-user-topics/categories.rst +++ b/docs/end-user-topics/categories.rst @@ -3,7 +3,7 @@ Categories A :ref:`dict category` is a grouping of Dockstore entries (tools, workflows, and notebooks) that share the same trait. Entries in a category might relate to the same scientific topic, perform the -same operation, or read/write the same type or format of data. +same operation, or input/output the same type of data or format. Dockstore places entries into categories to help users to better understand the entries, find entries relevant to a particular area of interest, @@ -69,3 +69,6 @@ page, click ``Manage Categories`` to view the entry's categories and approve or Dockstore-curated categories are managed exclusively by Dockstore curators. If you think an entry should be added to (or removed from) a Dockstore-curated category, reach out to the Dockstore team, for example via `Discourse `__. + +.. discourse:: + :topic_identifier: 12032