diff --git a/docs/_attic/glossary_entries.py b/docs/_attic/glossary_entries.py index ffca98ec..ac64fd66 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("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, input/output the same type of data 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 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='') + +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..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 @@ -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..14276129 --- /dev/null +++ b/docs/end-user-topics/categories.rst @@ -0,0 +1,74 @@ +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 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, +and discover entries that are similar to those they already know about. + +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 category bubbles are shown with a grey tint to distinguish them from Dockstore-curated +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:`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 +------------------------ + +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. + +The AI-curated categories are organized into six sets, each corresponding to a subontology of EDAM: + +* **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. + +Entry Owners Can Curate the AI +------------------------------ + +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 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 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. 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