Merge pull request #169 from monarch-initiative/240515-doc

Update documentation 230515

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
+

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

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: [email protected]
+
+
+## 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.
+
+

docs/general/MIRO.md

@@ -0,0 +1,3 @@
+# Minimum Information for the Reporting of an Ontology
+
+_Documentation coming up_

docs/general/contributors.md

@@ -0,0 +1,3 @@
+# VBO Contributors
+
+_Documentation coming up_

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

docs/general/references-cat.md → 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/

docs/general/references-dog.md → docs/general/sources-dog.md

@@ -1,4 +1,4 @@
-# References for Dog Breeds
+# Sources for Dog Breeds
 
 
 ## American Kennel Club (AKC)  

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.

docs/general/users.md

@@ -1,3 +1,4 @@
+# VBO Users and Use Cases
 
-# VBO Users
+_Documentation coming up_
 

docs/howto/howtouse.md

@@ -0,0 +1,2 @@
+# How to use VBO for data annotations
+_Documentation coming up_

docs/ontologymodeling/axioms.md

@@ -0,0 +1,3 @@
+# Axioms in VBO
+
+_Documentation upcoming_

docs/ontologymodeling/classification.md

@@ -0,0 +1,3 @@
+# VBO Classification
+
+_Documentation upcoming_

docs/ontologymodeling/merge-obsolete.md

@@ -0,0 +1,3 @@
+# When to merge and/or obsolete VBO terms
+
+_Documentation upcoming_

docs/ontologymodeling/metadata.md

@@ -0,0 +1,3 @@
+# VBO term Metadata
+
+_Documentation upcoming_

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. 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.
+
+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. 
+

docs/ontologymodeling/xref.md

@@ -0,0 +1,3 @@
+# VBO Database Cross-References
+
+_Documentation upcoming_

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,9 @@ 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
+  - Cite: cite.md
+  - FAQ: FAQ.md
+  - History: history.md