From c69da439cfa81799d83b67fbdaf75805ef741cc5 Mon Sep 17 00:00:00 2001 From: Sabrina Toro Date: Wed, 15 May 2024 15:51:47 -0700 Subject: [PATCH 1/4] Update documentation 230515 --- docs/FAQ.md | 13 +++++ ...e_obsolete.md => merge_obsolete_editor.md} | 0 docs/cite.md | 3 ++ docs/contributing.md | 49 +++++++++++++++++++ docs/general/MIRO.md | 3 ++ docs/general/contributors.md | 3 ++ docs/general/general.md | 2 +- docs/general/references-livestock.md | 23 --------- .../{references-cat.md => sources-cat.md} | 2 +- .../{references-dog.md => sources-dog.md} | 2 +- docs/general/sources-livestock.md | 29 +++++++++++ docs/general/users.md | 3 +- docs/howto/howtouse.md | 2 + docs/ontologymodeling/axioms.md | 3 ++ docs/ontologymodeling/classification.md | 3 ++ docs/ontologymodeling/merge-obsolete.md | 3 ++ docs/ontologymodeling/metadata.md | 0 .../term-labels-naming-conventions.md | 24 +++++++++ docs/ontologymodeling/xref.md | 3 ++ mkdocs.yaml | 27 +++++++--- 20 files changed, 162 insertions(+), 35 deletions(-) create mode 100644 docs/FAQ.md rename docs/VBO-editor-documents/{merge_obsolete.md => merge_obsolete_editor.md} (100%) create mode 100644 docs/general/MIRO.md create mode 100644 docs/general/contributors.md delete mode 100644 docs/general/references-livestock.md rename docs/general/{references-cat.md => sources-cat.md} (99%) rename docs/general/{references-dog.md => sources-dog.md} (99%) create mode 100644 docs/general/sources-livestock.md create mode 100644 docs/howto/howtouse.md create mode 100644 docs/ontologymodeling/axioms.md create mode 100644 docs/ontologymodeling/classification.md create mode 100644 docs/ontologymodeling/merge-obsolete.md create mode 100644 docs/ontologymodeling/metadata.md create mode 100644 docs/ontologymodeling/term-labels-naming-conventions.md create mode 100644 docs/ontologymodeling/xref.md diff --git a/docs/FAQ.md b/docs/FAQ.md new file mode 100644 index 0000000..8f39b1d --- /dev/null +++ b/docs/FAQ.md @@ -0,0 +1,13 @@ +# Frequently Asked Questions + +_Documentation coming up_ + +## General information about ontologies + + +## How to use GitHub to submit an issue + +## How to use GitHub to create a PR + +## How to open VBO in Protege + diff --git a/docs/VBO-editor-documents/merge_obsolete.md b/docs/VBO-editor-documents/merge_obsolete_editor.md similarity index 100% rename from docs/VBO-editor-documents/merge_obsolete.md rename to docs/VBO-editor-documents/merge_obsolete_editor.md diff --git a/docs/cite.md b/docs/cite.md index 3672a53..6af31fc 100644 --- a/docs/cite.md +++ b/docs/cite.md @@ -1 +1,4 @@ # How to cite VBO + +Use the following DOI to cite VBO: +doi: https://doi.org/10.5281/zenodo.7996674 \ No newline at end of file diff --git a/docs/contributing.md b/docs/contributing.md index 6d838da..b7f29a1 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1 +1,50 @@ # How to contribute to VBO + +We welcome any and all kinds of contributions, including: +- requests for changes in VBO, including new breed record, record duplication, incorrect breed information, or non-existent breeds. +- participation in discussions +- documentation improvements + +## Keep in touch + +The best way to be in touch with the VBO team is by creating an issue on our VBO GitHub repository: https://github.com/monarch-initiative/vertebrate-breed-ontology +See how to create a GitHub issue [here](https://oboacademy.github.io/obook/howto/term-request/) + +We also share information about upcoming events (e.g. workshops) and new VBO version releases via email. Please join the VBO mailing list: vbo-users+subconfirm@tislab.org + + +## Request changes in VBO +VBO is an open, community-driven ontology. We rely on the community to report errors or improvement in VBO based on their knowledge, experience, and use cases. + +All requests should be made by submitting an issue in our issue tracker https://github.com/monarch-initiative/vertebrate-breed-ontology/issues. Everyone is welcome and encouraged to submit an issue: all that is required is a GitHub account, which can be created for free [here](https://github.com/signup?user_email=&source=form-home-signup). + +**New term requests** +When a breed term cannot be found in VBO, one can submit a request to add it. + +A good term request includes: +- the most common name for the breed (required*) +- the species of the breed (required*) +- any synonyms for the breed name +- any publication (e.g. PMID), references, and/or databases supporting the information (required*) +- the ORCID of the requester (so we can give you credit in the ontology) + +Please note that bulk submissions (i.e. requesting more than one term at a time) are welcome. The VBO team can guide you through the best way to submit these requests in a spreadsheet format. + +**changes to an existing VBO term** +It is possible that some information that is currently in VBO needs to be updated. These changes can include adding new synonyms or new sources of information, merging duplicate records into a single one, or removing a record representing a breed that never existed. + +For these requests, please add as much information as you can in the GitHub issue. Please make sure to include: +- the VBO ID of the existing term for which changes are requested +- any publication (e.g. PMID), references, databases supporting your request +- the ORCID of the requester (so we can give you credit in the ontology) + +## Participate in the discussions +We aim to make VBO development and maintenance a transparent process where decisions about changes and ontology modeling are not only available to the community, but also includes community feedback and participation. Community members are encouraged to participate in the conversation on existing GitHub issues and share their agreement, disagreement, and/or suggestions based on their expertise and knowledge. +Anyone is able to comment on any GitHub issues, as long as they have a GitHub account, which can be created [here](https://github.com/signup?user_email=&source=form-home-signup). + +## Make changes in VBO: +We welcome suggestions and updates to our documentation via Pull Requests in GitHub. (Please see [here](_LINK to be added_) for instruction on how to create a Pull Request) + +The current system to maintain VBO is based on spreadsheets/components (LINK to somewhere in the document), which is incompatible with changes being made directly in the ontology (ie changes to vbo-edit.owl file) as it is custom in other ontologies. If you are interested in being part of the VBO editor team and make changes directly to the ontology, please reach out to us (AT THIS EMAIL), and we will be happy to train you on the ontology editing. + + diff --git a/docs/general/MIRO.md b/docs/general/MIRO.md new file mode 100644 index 0000000..8b19fd5 --- /dev/null +++ b/docs/general/MIRO.md @@ -0,0 +1,3 @@ +# Minimum Information for the Reporting of an Ontology + +_Documentation coming up_ diff --git a/docs/general/contributors.md b/docs/general/contributors.md new file mode 100644 index 0000000..5b666a5 --- /dev/null +++ b/docs/general/contributors.md @@ -0,0 +1,3 @@ +# VBO Contributors + +_Documentation coming up_ diff --git a/docs/general/general.md b/docs/general/general.md index c731514..74a5ae5 100644 --- a/docs/general/general.md +++ b/docs/general/general.md @@ -12,7 +12,7 @@ Maybe definitions of 'breed' exist in the literature and in different communitie Breeds included in VBO have been characterized, defined, and determined by international breed organizations, communities, experts, and/or have been reported in the literature (see table below). -## References organizations +## Breed information sources The following table includes breed organizations, communities, and experts which reported, characterized, defined, and/or determined the breeds included in VBO |Breeds| Sources| Sources links diff --git a/docs/general/references-livestock.md b/docs/general/references-livestock.md deleted file mode 100644 index cadc9aa..0000000 --- a/docs/general/references-livestock.md +++ /dev/null @@ -1,23 +0,0 @@ - -# References for Livestock Breeds - -## Domestic Animal Diversity Information (DAD-IS) -**Home page:** https://www.fao.org/dad-is - -**Description:** -DAD-IS is a list compiled and maintained by the Food and Agriculture Organization of the United Nations (FAO). This list contains information on more than 15,000 national breed populations representing more than 8,800 breeds across 38 species. It is assembled, contributed to, and updated by country-nominated National Coordinators from 182 countries. - -**Data breeds notes:** -DAD-IS represents 2 types of breeds: “local breeds” (breeds reported in a single country), and “transboundary breeds” (breeds reported in several different countries). The instance of “transboundary breeds” that are reported in specific countries are called in DAD-IS “national breed populations” - -In addition to the breeds' most common name and country of existence, DAD-IS reports on the domestication status, the extinction status of breeds, and the description of origin of the breeds. - -**Data synchronization:** -the data in VBO coming from this source is currently not regularly updated. - -## Livestock Breeds - Livestock Breed Ontology (LBO) -**Home page:** https://www.animalgenome.org/bioinfo/projects/lbo/ - -**Description:** -*(upcoming)* - diff --git a/docs/general/references-cat.md b/docs/general/sources-cat.md similarity index 99% rename from docs/general/references-cat.md rename to docs/general/sources-cat.md index ded10b6..50ec8b4 100644 --- a/docs/general/references-cat.md +++ b/docs/general/sources-cat.md @@ -1,5 +1,5 @@ -# References for Cat Breeds +# Sources for Cat Breeds ## The Cat Fanciers’ Association (CFA) **Home page:** https://cfa.org/ diff --git a/docs/general/references-dog.md b/docs/general/sources-dog.md similarity index 99% rename from docs/general/references-dog.md rename to docs/general/sources-dog.md index dfea318..801b158 100644 --- a/docs/general/references-dog.md +++ b/docs/general/sources-dog.md @@ -1,4 +1,4 @@ -# References for Dog Breeds +# Sources for Dog Breeds ## American Kennel Club (AKC) diff --git a/docs/general/sources-livestock.md b/docs/general/sources-livestock.md new file mode 100644 index 0000000..a06dfb5 --- /dev/null +++ b/docs/general/sources-livestock.md @@ -0,0 +1,29 @@ + +# Sources for Livestock Breeds + +## Domestic Animal Diversity Information (DAD-IS) +**Home page:** https://www.fao.org/dad-is + +**Description:** +DAD-IS is a list compiled and maintained by the Food and Agriculture Organization of the United Nations (FAO). This list contains information on more than 15,000 national breed populations representing more than 8,800 breeds across 38 species. It is assembled, contributed to, updated, and maintained by country-nominated National Coordinators from 182 countries. The goal of DAD-IS is the Management of Animal Genetic Resources, focusing on diversity of livestock breeds on national, regional and global levels including the status of breeds regarding their risk of extinction. + +**Data breeds notes:** +Because of the specific goal of DAD-IS and how it is maintained, breeds and breed information are specific to these breeds’ country localization as reported by the National Coordinators. +DAD-IS makes the distinction between 2 types of breeds: “local breeds” (breeds reported in a single country), and “transboundary breeds” (breeds reported in several different countries). The instance of a “transboundary breed” that are reported in specific countries is called in DAD-IS “national breed populations”. +Breeds in the DAD-IS list (except for the “transboundary” breeds) therefore represent instances of breeds located in a specific country as reported by the National Coordinators. This concept is specific to DAD-IS, and is represented accordingly in VBO as “breed located_in a specific country”. +VBO users should be aware of this concept, as they are unique to DAD-IS and rarely used in other contexts. + +**Data synchronization:** +the data in VBO coming from this source is currently not regularly updated. + +## Livestock Breeds - Livestock Breed Ontology (LBO) +**Home page:** https://www.animalgenome.org/bioinfo/projects/lbo/ + +**Description:** +LBO is a controlled, publicly available and regularly updated and released vocabulary for the unambiguous description of buffalo, cattle, chicken, goat, horse, pig, and sheep breeds. Its utility includes proper identification of inherited variation sources in genetics/genomic studies. There are currently 1,129 classes in LBO. LBO metadata includes synonyms and description of origin. + +**Data breeds notes:** +LBO terms were included in VBO as database cross-references. + +**Data synchronization:** +the data in VBO coming from this source is currently not regularly updated. \ No newline at end of file diff --git a/docs/general/users.md b/docs/general/users.md index 0e387c0..4d482cd 100644 --- a/docs/general/users.md +++ b/docs/general/users.md @@ -1,3 +1,4 @@ +# VBO Users and Use Cases -# VBO Users +_Documentation coming up_ diff --git a/docs/howto/howtouse.md b/docs/howto/howtouse.md new file mode 100644 index 0000000..2ff67b8 --- /dev/null +++ b/docs/howto/howtouse.md @@ -0,0 +1,2 @@ +# How to use VBO for data annotations +_Documentation coming up_ diff --git a/docs/ontologymodeling/axioms.md b/docs/ontologymodeling/axioms.md new file mode 100644 index 0000000..f621ce1 --- /dev/null +++ b/docs/ontologymodeling/axioms.md @@ -0,0 +1,3 @@ +# Axioms in VBO + +_Documentation upcoming_ \ No newline at end of file diff --git a/docs/ontologymodeling/classification.md b/docs/ontologymodeling/classification.md new file mode 100644 index 0000000..3450824 --- /dev/null +++ b/docs/ontologymodeling/classification.md @@ -0,0 +1,3 @@ +# VBO Classification + +_Documentation upcoming_ \ No newline at end of file diff --git a/docs/ontologymodeling/merge-obsolete.md b/docs/ontologymodeling/merge-obsolete.md new file mode 100644 index 0000000..56b610d --- /dev/null +++ b/docs/ontologymodeling/merge-obsolete.md @@ -0,0 +1,3 @@ +# When to merge and/ore obsolete VBO terms + +_Documentation upcoming_ \ No newline at end of file diff --git a/docs/ontologymodeling/metadata.md b/docs/ontologymodeling/metadata.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/ontologymodeling/term-labels-naming-conventions.md b/docs/ontologymodeling/term-labels-naming-conventions.md new file mode 100644 index 0000000..80da16d --- /dev/null +++ b/docs/ontologymodeling/term-labels-naming-conventions.md @@ -0,0 +1,24 @@ +# Term labels and Naming Conventions + +One can refer to the same breed by multiple names, including names in different languages (e.g. ‘Artois Hound’ and ‘Chien d’Artois’ refer to the same breed). In addition, the same name is often used to refer to different breeds, of different species. For example, “Tibetan” is the name for a breed of cattle, sheep, chicken, pig, goat, etc. However, a VBO term label must be unique, i.e. multiple terms cannot have the same label, even if their names are the same. In this document, we explain how VBO term labels were created to ensure uniqueness and uniformity. + +Breeds from different species often share the same name. For example, “Tibetan” is the name for a breed of cattle, sheep, chicken, pig, goat, etc. In addition, some breeds are commonly called by names that can represent other types of entities. For example “Cyprus” is used to refer to breeds of cattle, cat, etc., but also to the country “Cyprus”. +To create unique VBO term labels, we concatenated the breed’s most common name and their species, following the format: `**'Most common name (Species)'**`, in which most common name and species are the English language names (e.g. 'Cyprus (Cat)' VBO:0100081). + +The “Most common name” represents the breed name that is most often used to refer to the breed, as determined by the information found in the sources (_LINK to be added_). This ‘most common name’ is also recorded as an “exact synonym” [_LINK to be added_]. All breed names, including the one that are shared between breeds, are available as synonyms in VBO. For example, an exact synonym of Tibetan (Goat) VBO:0000845 is Tibetan. + +Including the ‘Species’ in the term label could be controversial. Breeds have a is_a relationship to a species, and therefore repeating the species name (ie ontological parentage) in the label is a break with standard ontology practices. While we recognize that this solution is not ideal, we were unable to ensure term label uniqueness without including the species name in the term label. As exemplified above, breeds from different species can share the same name, and some breeds can share identical name with other types of entities such as countries. + + +**The case of DAD-IS “national breed population” and “local breeds”.** +DAD-IS is maintained by National Coordinators for the Management of Animal Genetic Resources, and therefore their concept of breed is closely tight to the country where a breed has been reported (read more about DAD-IS [here](_LINK to be added_)). +DAD-IS distinguishes between: +- “national breed population” which refers to the existence of a particular breed in a particular country. For example, a breed of chicken called “Alatau” reported to exist in Kyrgyzstan (VBO:0007427) +- “local breed” which refers to a country specific instance of a same breed that exists in each of several countries (itself called “transboundary” breed). (see example below) + +As a consequence, it is very common to find breeds in DAD-IS with the same common name and from the same species. For example, “Jersey Giant” is a breed of chicken that exists in Canada, Ireland, Luxembourg, etc., with each instance of this breed in an individual county being considered as an individual breed record to be represented in VBO. +The naming convention reported above, based on “most common name” and “species” is therefore not sufficient to ensure term label uniqueness for DAD-IS “national breed population” and “local breed”. The country where the breed has been reported by the National Coordinators had to be included to the VBO term label, following the format: +`**'Most common name’, Country (Species)'**`, in which country and species are the English names (e.g ‘Jersey Giant, Canada (Chicken)’ VBO:0006068). + +We recognize that adding the Ccuntry of existence in the term name, in addition to the species, is not ideal and is unusual to ontology practices, but this concatenation of attributes was the only viable solution to ensure term uniqueness. + diff --git a/docs/ontologymodeling/xref.md b/docs/ontologymodeling/xref.md new file mode 100644 index 0000000..7c1cca5 --- /dev/null +++ b/docs/ontologymodeling/xref.md @@ -0,0 +1,3 @@ +# VBO Database Cross-References + +_Documentation upcoming_ \ No newline at end of file diff --git a/mkdocs.yaml b/mkdocs.yaml index 87319e7..e500795 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -4,15 +4,23 @@ nav: - Getting started: index.md - VBO general information: - VBO general information: general/general.md - - References for Livestock Breeds: general/references-livestock.md - - References for Cat Breeds: general/references-cat.md - - References for Dog Breeds: general/references-dog.md + - VBO MIRO information: general/MIRO.md + - VBO Contributors: general/contributors.md + - VBO Users and Use cases: general/users.md + - Sources for Livestock Breeds: general/sources-livestock.md + - Sources for Cat Breeds: general/sources-cat.md + - Sources for Dog Breeds: general/sources-dog.md + - Ontology Modeling: + - VBO Classification: ontologymodeling/classification.md + - VBO term Metadata: ontologymodeling/metadata.md + - Label and Naming Conventions: ontologymodeling/term-labels-naming-conventions.md + - Axioms in VBO: ontologymodeling/axioms.md + - Database Cross-References: ontologymodeling/xref.md + - Term merge and obsolete: ontologymodeling/merge-obsolete.md - VBO Developer Docs: - Components: VBO-editor-documents/components.md - Release process: VBO-editor-documents/release.md - - Merging/obsoleting classes: VBO-editor-documents/merge_obsolete.md - - Cite: cite.md - - History: history.md + - Merging/obsoleting classes: VBO-editor-documents/merge_obsolete_editor.md - How-to guides: - Standard ODK workflows: - Overview: odk-workflows/index.md @@ -24,5 +32,8 @@ nav: - Managing the documentation: odk-workflows/ManageDocumentation.md - Continuous Integration: odk-workflows/ContinuousIntegration.md - Your ODK Repository Overview: odk-workflows/RepositoryFileStructure.md - - Contributing: contributing.md - + - Contribute: contributing.md + - Use VBO for data annotation: howto/howtouse.md + - Cite: cite.md + - FAQ: FAQ.md + - History: history.md \ No newline at end of file From e7e4a7bdca2f559c3d3c07227276f54f95ccb72e Mon Sep 17 00:00:00 2001 From: Sabrina Toro Date: Wed, 15 May 2024 15:59:55 -0700 Subject: [PATCH 2/4] Update mkdocs.yaml --- mkdocs.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yaml b/mkdocs.yaml index e500795..9683bb4 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -34,6 +34,7 @@ nav: - Your ODK Repository Overview: odk-workflows/RepositoryFileStructure.md - Contribute: contributing.md - Use VBO for data annotation: howto/howtouse.md + - Cite: cite.md - Cite: cite.md - FAQ: FAQ.md - History: history.md \ No newline at end of file From 2141fdc39a3f6b0cefba51d55a1fddbb657264a2 Mon Sep 17 00:00:00 2001 From: Sabrina Toro Date: Thu, 16 May 2024 07:44:24 -0700 Subject: [PATCH 3/4] updated typo and naming convention doc --- docs/ontologymodeling/merge-obsolete.md | 2 +- docs/ontologymodeling/term-labels-naming-conventions.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/ontologymodeling/merge-obsolete.md b/docs/ontologymodeling/merge-obsolete.md index 56b610d..1a83bef 100644 --- a/docs/ontologymodeling/merge-obsolete.md +++ b/docs/ontologymodeling/merge-obsolete.md @@ -1,3 +1,3 @@ -# When to merge and/ore obsolete VBO terms +# When to merge and/or obsolete VBO terms _Documentation upcoming_ \ No newline at end of file diff --git a/docs/ontologymodeling/term-labels-naming-conventions.md b/docs/ontologymodeling/term-labels-naming-conventions.md index 80da16d..47e47e6 100644 --- a/docs/ontologymodeling/term-labels-naming-conventions.md +++ b/docs/ontologymodeling/term-labels-naming-conventions.md @@ -1,8 +1,8 @@ # Term labels and Naming Conventions -One can refer to the same breed by multiple names, including names in different languages (e.g. ‘Artois Hound’ and ‘Chien d’Artois’ refer to the same breed). In addition, the same name is often used to refer to different breeds, of different species. For example, “Tibetan” is the name for a breed of cattle, sheep, chicken, pig, goat, etc. However, a VBO term label must be unique, i.e. multiple terms cannot have the same label, even if their names are the same. In this document, we explain how VBO term labels were created to ensure uniqueness and uniformity. +One can refer to the same breed by multiple names, including names in different languages (e.g. ‘Artois Hound’ and ‘Chien d’Artois’ refer to the same breed). In addition, the same name is often used to refer to different breeds, of different species. For example, “Tibetan” is the name for a breed of cattle, sheep, chicken, pig, goat, etc. Some breeds are also commonly called by names that can represent other types of entities. For example “Cyprus” is used to refer to breeds of cattle, cat, etc., but also to the country “Cyprus”. +A VBO term label must be unique, i.e. multiple terms cannot have the same label, even if their names are the same. In this document, we explain how VBO term labels were created to ensure uniqueness and uniformity. -Breeds from different species often share the same name. For example, “Tibetan” is the name for a breed of cattle, sheep, chicken, pig, goat, etc. In addition, some breeds are commonly called by names that can represent other types of entities. For example “Cyprus” is used to refer to breeds of cattle, cat, etc., but also to the country “Cyprus”. To create unique VBO term labels, we concatenated the breed’s most common name and their species, following the format: `**'Most common name (Species)'**`, in which most common name and species are the English language names (e.g. 'Cyprus (Cat)' VBO:0100081). The “Most common name” represents the breed name that is most often used to refer to the breed, as determined by the information found in the sources (_LINK to be added_). This ‘most common name’ is also recorded as an “exact synonym” [_LINK to be added_]. All breed names, including the one that are shared between breeds, are available as synonyms in VBO. For example, an exact synonym of Tibetan (Goat) VBO:0000845 is Tibetan. From ffdf115553528a5fd4cffff66dd40dcf9ca6cbba Mon Sep 17 00:00:00 2001 From: Sabrina Toro Date: Thu, 16 May 2024 08:25:50 -0700 Subject: [PATCH 4/4] Update metadata.md --- docs/ontologymodeling/metadata.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/ontologymodeling/metadata.md b/docs/ontologymodeling/metadata.md index e69de29..fd3711e 100644 --- a/docs/ontologymodeling/metadata.md +++ b/docs/ontologymodeling/metadata.md @@ -0,0 +1,3 @@ +# VBO term Metadata + +_Documentation upcoming_ \ No newline at end of file