Merge pull request #55 from EBISPOT/ethnicity_refactor

Release 2024-04-25

docs/contributing.md

@@ -7,12 +7,12 @@
 
 ## Guidelines for creating GitHub tickets with contributions to the ontology:
 
-1. **Write a detailed request:** Please be specific and include as many details as necessary, providing background information, and if possible, suggesting a solution. GOC editors will be better equipped to address your suggestions if you offer details regarding *'what is wrong'*, *'why'*, and *'how to fix it'*.
+1. **Write a detailed request:** Please be specific and include as many details as necessary, providing background information, and if possible, suggesting a solution. HANCESTRO editors will be better equipped to address your suggestions if you offer details regarding *'what is wrong'*, *'why'*, and *'how to fix it'*.
 
 2. **Provide examples and references:** Please include PMIDs for new term requests, and include also screenshots, or URLs illustrating the current ontology structure for other types of requests. 
 
 3. **For new term request:** Be sure to provide suggestions for label (name), definition, references, position in hierarchy, etc.
 
 4. **For updates to relationships:** Provide details of the current axioms, why you think they are wrong or not sufficient, and what exactly should be added or removed.
 
-On behalf of the hancestro editorial team, Thanks!
+On behalf of the HANCESTRO editorial team, Thanks!

docs/index.md

@@ -29,14 +29,29 @@ Ancestry categories in the Human Ancestry Ontology refer to genetic ancestry and
 
 The key purpose of HANCESTRO is the capture of the primary ancestry categories defined in [Morales et al, 2018](https://genomebiology.biomedcentral.com/articles/10.1186/s13059-018-1396-2). Where additional genetic information for a smaller population category (eg by country) is available to assign it to one of the defined ancestry categories, this is also represented in the ontology hierarchy. However a lot of country-based categories are either uncategorised, ie the available ancestry information does not fall into one of the defined categories or they are undefined, ie insufficient information is available to allocate this population to a specific ancestral group.
 
- The primary asserted relationship between ancestry categories and countries is via the `isDemonymOf` relationship, which identifies that individuals may be residents or natives of a particular place but makes no assertion regarding their genetic background.
+The primary asserted relationship between ancestry categories and countries is via the `isDemonymOf` relationship, which identifies that individuals may be residents or natives of a particular place but makes no assertion regarding their genetic background.
 
 In exceptional cases, ancestry categories are associated with countries via the `hasCountryOfOrigin` relationship. This is much more formal definition generally reserved for genetically isolated populations where objectively verifiable information is available to relate individuals from this population to a small geographic area within a certain country.
 
+### Ethnicity category
+
+Many population descriptors do not fully match defined ancestry populations although individuals from these populations may show some levels of genetic similarity with a given ancestry category. Ethnicity descriptors are more likely to describe populations groups with a similar cultural, religious, tribal, geographic or other social background. This includes terms such as `Jewish Israeli`, `Punjabi Sikh` or `Hispanic`. 
+
+In order to make HANCESTRO more broadly useful for the annotation of both self-reported information, usually referred to as `self-reported ethnicity` as well as genetic ancestry inferred from the similarity of individuals' sequence data to reference populations, we created a new `ethicity category (HANCESTRO:0601)`. This is a grouping class for all terms in HANCESTRO used to describe populations for which no genetic reference population is available and that are also not geographic descriptors. 
+
+
+### Geographic category
+
+One common way to describing individuals is by reference to the location where they were born, where they live or where their family origniated, such as [national or regional demonyms](https://en.wikipedia.org/wiki/Demonym). Demonyms are used to designate all people in relation to a particular place, regardless of ethnic, linguistic, religious or other cultural considerations.
+
+In order to make it easier for HANCESTRO users to identify all geographical descriptors, we implemented a new `geographic category (HANCESTRO:0602)` that groups all country and regional demonyms.   
+
+
 ### Ancestry status
 
 This class represents the general characterisation of the ancestry of a population or individual. Ancestry status can either be admixed or genetically isolated.
 
+
 ### Continent
 
 Formally defined major geographic area.

docs/ontology_patterns.md

@@ -0,0 +1,69 @@
+# human-ancestry-ontology-design-patterns
+
+HANCESTRO design patterns
+========
+
+## HANCESTRO native object properties
+
+HANCESTRO defines 4 native object properties:
+
+- hasAncestryStatus (HANCESTRO:0301)
+- hasCountryOfOrigin (HANCESTRO:0308)
+- isDemonymOf (HANCESTRO:0330)
+- hasDemonym (HANCESTRO:0329)
+
+In addition, it uses several imported properties:
+
+- has quality (RO:0000086)
+- located in (RO:0001025)
+- part of (BFO:0000050)
+
+
+## Defined classes
+
+### Ancestry status
+
+`ancestry status` is defined as being equivalent to `genetically isolated ancestry or admixed ancestry`. It is a grouping class for population genetics qualifiers.
+
+
+### Ethnicity category
+
+`ethnicity category`is defined as being equivalent to `has quality some ethnicity descriptor`. This means that any subclass of `ethnicity category` has an inherent quality of being a descriptor of type ethnicity.
+
+### Geographic category
+
+`geographic category`is defined as being equivalent to `(isDemonymOf some Country) or (has quality some geographic descriptor)`. This means that any subclass of `geographic category` is either directly identified as a denomym of a country identified in the ontology or it has an inherent quality of being a descriptor of type geography.
+
+
+## Other design patterns
+
+### Country-region links
+
+Where possible, we create a link between each country and the sub-continental region it is part of using the pattern
+
+```located in only <region>```
+
+Where a country spans multiple regions, we aim to list all of them. The reason for this axiomatisation is to enable queries by region, such as "Give me all countries located in Eastern Asia".
+
+We acknowledge that the use of `only` in OWL axioms is not optimal and are actively looking into alternative design patterns. 
+
+
+### Region-continent links
+
+For similar reasons as for the country-region links, we also create a link between each the sub-continental region and the continent it is part of using the pattern
+
+```part of only <continent>```
+
+
+We again acknowledge that the use of `only` in OWL axioms is not optimal and are actively looking into alternative design patterns. 
+
+### Country-demonym links
+
+As mentioned in the section on defined classes, we create links between geographic population descriptors for countries and the country they are associated with using the pattern
+
+```isDemonymOf some <country>```
+
+
+### Country of origin
+
+In exceptional cases, ancestry categories are associated with countries via the `hasCountryOfOrigin` relationship. This is a fairly formal definition generally reserved for genetically isolated populations where objectively verifiable information is available to relate individuals from this population to a small geographic area within a certain country. We do not use