Added genetic diversity fields - Fixes #1610

[arschat]

Release notes

#1610

For human_specific.json schema:

• ethnicity_question
• ethnicity_parents
• primary_language
• mother_father_language
• current_residence
• place_of_birth

For residence.json schema:

• country
• granular
• duration
• area_type

For medical_history.json schema:

• diet_meat_consumption
• reproduction_history

For reproduction_history.json schema:

• menarche_age
• menopause_status
• parity
• gravidity

Reviews requested

• Need 4 Reviewers to approve because this is a major update

[idazucchi]

Nice job! It's well organised, I've left some comments so we can discuss a few things

[hannes-ucsc]

Which project/dataset is this for?

[arschat]

Hi @hannes-ucsc this PR is not for a specific project/dataset.

These are the recommendation metadata fields from the HCA Genetic Diversity TaskForce to record the genetic, geographic and in generally human diversity in the HCA studies.

Do you have any specific concerns?

[hannes-ucsc]

I may be out of the loop, but if this isn't going to be used for any actual projects, why is it being added to the schema?

I am worried that this isn't sufficiently modular, risking for human-specific and medical history modules to become a kitchen sink of fields, i.e. a flat, unstructured list of fields, some related and some not. This will make comprehending the schema (and the JSON documents compliant with it) increasingly difficult. For example, menarche_age, menopause_status, parity and gravidity are all clearly related but they are not encapsulated in a module. Another example are the place_of_birth_… fields. The fact that their names all share a prefix is somewhat of a design smell, indicating that they, too, want to be encapsulated. The ethnicity-related fields added here appear to relate to a questionnaire of some sort, similarly suggesting that they should be encapsulated in a module.

[arschat]

Thank you for your comment Hannes.

Bionetwork coordinators have requested around 250 fields of Tier 2 bionetwork-specific metadata that do not exist currently into our schema. Since the Tier 2 collection has not been officially started yet, we cannot be sure of how frequent all of those fields will be filled. We've shared our concerns with bionetwork coordinators on the feasibility of the metadata collection, but we trust their confidence on the collection.

Regarding the modularity. There are indeed some fields that could be clustered together but we choose this modelling to avoid extensive "module-in-a-module" structure since we've avoided this until now (with the exception of ontology modules). I am happy to encapsulate similar fields in modules either inside human_specific/ medical_history modules or as separate modules in donor_organism if you prefer this modelling.

[hannes-ucsc]

Bionetwork coordinators have requested around 250 fields of Tier 2 bionetwork-specific metadata that do not exist

If I understand you correctly, this PR is just the first slate of a series of fairly involved changes. Since it is extremely difficult to fix the schema once metadata using it has been released, it is very important that we get this right from the beginning. Is there any substantive documentation about this effort that you could share?

avoid extensive "module-in-a-module" structure since we've avoided this until now

Given the sheer number of new fields you cite, lack of modularity is a serious concern. I don't see why nesting modules is problematic. Hierarchical structures are commonplace in computer science—in biology, too, for that matter—and have proven to be a useful modeling approach.

[arschat]

Hi @hannes-ucsc I understand your concerns whether this definitions are going to be adopted by contributors in this way or not.
However this PR, is about the additional Genetic Diversity fields, that have been suggested by the Human Cell Atlas Genetic Divesity Taskforce, have been accepted by the HCA Organization Committee and are going to be requested across all bionetworks' Tier 2 metadata. Thus, they are unlikely to be changed.

Given your feedback on modularity, I refactored some fields in a more modular way. Let me know if this works better for you. I could split into different PRs for each module but please let me know your comments here before we move into new PRs.

[hannes-ucsc]

Some countries don't call the first level subdivision "state" and some countries are known under various different names, in addition to the fact that most countries have a name in their native language and English.

Taking inspiration from https://schema.org/PostalAddress, this should be split into country (as a two letter ISO code) and region.

[idazucchi]

This is an interesting suggestion, however ISO country codes are not commonly used in biological research so it would be an added burden on who is preparing the metadata.
Is there an easy way to validate the iso codes within our schema, other than adding manually all the codes as an enum? I think it's worth using the ISO standard only if it can allow us to easily validate the country names, which we can't do with the current schema

[hannes-ucsc]

however ISO country codes are not commonly used in biological research …

I don't claim to be an authority on biomedical research but I find that hard to believe. Would you be able provide evidence that supports your claim? A quick Google search immediately brings up anecdotal evidence that appears to contradict it. For example, NIH's NLM style guide recommends using country codes, the BCO ontology has a property for it, and Our World In Data tracks COVID across the globe using three-letter country codes, albeit in a different, now discouraged three-letter form.

… so it would be an added burden on who is preparing the metadata

To confirm, the burden you are referring to is having to Google "iso country code France"? Should we not also consider the burden on the user who has to consolidate various ambiguous, misspelled or localized country names (United Kingdom/Great Britain, Italy/Italia and so on)?

Is there an easy way to validate the iso codes within our schema.

Of course. All that's needed is an enum of the country codes. OCDS for example, maintains one: https://github.com/open-contracting/standard/blob/68db85199bea30e22d4d936abcb7564d213c82e5/schema/release-schema.json#L1963

[arschat]

Hi @hannes-ucsc , INSDC uses a full name country list. ENA and BioSamples use this list to record the name of geographic sampling location. Do you think we could use this list here?

[hannes-ucsc]

You'd maintain a copy of the list as an enum as part of the schema?

[arschat]

Yes, we can use the enum list that ENA uses after removing the missing related & NA values in the end.

[hannes-ucsc]

Suggested change

	"granular_location": {
	"locality": {

[hannes-ucsc]

Suggested change

	"ethnicity_parents": {
	"parental_ethnicities": {

Just a suggestion

[hannes-ucsc]

Or, in line with my comment below

Suggested change

	"ethnicity_parents": {
	"ethnicity_of_parents": {

[hannes-ucsc]

Suggested change

	"mother_father_language": {
	"first_language": {

[arschat]

According to the Taskforce guidelines, this is about the language that the donor parents speak. Not necessarily the first language the donor spoke.
Maybe we could revert to parents_language to distinguish between "first language" and "language of mother".

[hannes-ucsc]

In this PR, this field is currently documented as

Ancestral language(s), spoken by parents (“mother tongue” and / or “father tongue”) and / or grandparents. Can include dialects (for example, Hokkien).

"Mother tongue" typically means one's native language, not the language spoken by one's mother. To avoid confusion, I would prefer we avoid the terms "mother/father tongue" completely. "Ancestral language" usually means the opposite of modern language. I would also avoid that.

As for the name of the property, I propose that we establish a convention for naming properties of immediate ancestors (parents) or ancestors in general. Prefixing the property name with parental_ or ancestral_ comes to mind but then the aforementioned ambiguity arises. Since it is not possible to include an apostrophe in a property name, I wouldn't use "parents_" as that could be the plural "parents" or a possessive "parent's".

My preferred choice would be the suffix "_of_parents" and "_of_ancestors", applied to all such properties across this PR. I would include great grand parents in this property as it seems arbitrary to draw the line above the grand parents.