Metadata integration - bio_characteristics and location, mostly

.gitignore

@@ -84,3 +84,5 @@ target/
 
 #********* Java artifacts *******
 *.class
+
+*.py

doc/source/api/biometadata.rst

@@ -1,9 +1,5 @@
 .. _biometadata:
 
-.. image:: /_static/biometadata_schema.svg
-   :width: 184 px
-   :align: right
-
 .. _biometadata_biosample:
 
 *******************************
@@ -37,7 +33,7 @@ Attribute             Notes
 *name*                * a human readable object label/identifier
                       * not to be used for referencing
 *description*         * additional, unstructured information about this Biosample
-*disease*             * OntologyTerm annotating the disease of the sample
+*bio_characteristics*     * contains lists of phenotypes, diseases and other information associated with this Biosample, in the form of BioCharacteristic objects
 *individualId*        * the *id* of the *Individual* this Biosample was derived from
 *created*             * the time the record was created, in ISO8601
 *updated*             * the time the record was updated, in ISO8601
@@ -57,6 +53,11 @@ An *Individual* is a GA4GH data object representing a biological instance
 (most commonly a human being or other individual organism) on whose *Biosamples*
 experimental analyses are performed.
 
+In the case of metagenome analyses (i.e. when the biosample consists of
+material like patient derived sputum, analyzed for its microbial content), the
+"species" context would still be the host; identified guest species would
+be described in analysis results.
+
 Individual attributes
 =====================
 
@@ -69,9 +70,25 @@ Attribute             Notes
 *name*                * a human readable object label/identifier
                       * not to be used for referencing
 *description*         * additional, unstructured information about this Individual
+*bio_characteristics*     * contains lists of phenotypes, diseases and other information associated with this Individual, in the form of BioCharacteristic objects
 *species*             * OntologyTerm representing the species (NCBITaxon:9606)
 *sex*                 * OntologyTerm for the genetic sex of this individual.
 *created*             * the time the record was created, in ISO8601
 *updated*             * the time the record was updated, in ISO8601
 *attributes*          * additional, structured information
 ===================== ==========================================================
+
+.. _biometadata_BioCharacteristic:
+
+***************************************
+BioMetadata: *BioCharacteristic* Object
+***************************************
+
+BioCharacteristic in the GA4GH Schema
+-------------------------------------
+
+A BioCharacteristic is an object, defining a single phenotype or diagnosis
+through the use of a free text description and a representation by one or
+more "ontologyTerms" objects as well as zero or more "negatedOntologyTerms".
+An additional "scope" attribute allows to limit queries e.g. to "disease" type
+objects.

doc/source/appendix/ontologies.rst

@@ -38,7 +38,7 @@ What is the minimum attribute requirement for  OntologyTerm in GA4GH?
 
 Conceptually (and consistent with the metadata branch)
 
-:termId:
+:term_id:
   required and implemented as CURIE
   we assume this resolves to a meaningful document, e.g. http://purl.obolibrary.org/obo/SO_0000147, using a prefix mapper, e.g. SO: <=> http://purl.obolibrary.org/obo/SO_
 :term:
@@ -80,45 +80,41 @@ Examples
 Genotypic sex
 =============
 
-:termId:
+:term_id:
 	"PATO:0020001",
 :term:
   "male genotypic sex" ,
 
 
-
 Sequence Ontology
 =================
 
-:termId:
+:term_id:
   "SO:0001583",
 :term:
 	"missense_variant",
 
 
-
 Human Phenotype ontology
 ========================
 
-:termId:
+:term_id:
   "HP:0000819",
 :term:
-	"Diabetes mellitus",
-
+  "Diabetes mellitus",
 
 ----
 
-:termId:
-	"HP:0012059",
+:term_id:
+  "HP:0012059",
 :term:
-	"Lentigo maligna melanoma",
-
+  "Lentigo maligna melanoma",
 
 
 Body part (Uberon)
 ==================
 
-:termId:
+:term_id:
 	"UBERON:0003403",
 :term:
 	"skin of forearm",
@@ -127,7 +123,7 @@ Body part (Uberon)
 Human disease ontology
 ======================
 
-:termId:
+:term_id:
 	"DOID:9351",
 :term:
 	"diabetes mellitus",
@@ -136,26 +132,23 @@ Human disease ontology
 Experimental factor ontology
 ============================
 
-:termId:
+:term_id:
 	"EFO:0000400",
 :term:
 	"diabetes mellitus",
 
-
 ----
 
-:termId:
+:term_id:
 	"EFO:0004422",
 :term:
 	"exome",
 
 
-
 Unit Ontology
 =============
 
-:termId:
+:term_id:
 	"UO:0000016",
 :term:
 	"millimetre",
-

src/main/proto/ga4gh/bio_metadata.proto

@@ -23,6 +23,17 @@ message Individual {
   // The "description" attributes should not contain any structured data.
   string description = 4;
 
+  // The bio_characteristics attribute uses lists of BioCharacteristic objects to describe
+  // diseases, phenotypes ... associated with this Individual. The values here may
+  // overlap with values recorded in related records. As general rule, "germline"
+  // or non-organ specific afflictions ("Li-fraumeni Syndrome", "Diabetes mellitus"
+  // should be recorded here, whereas "Infiltrating duct carcinoma" may be both
+  // recorded here (as known disease history)
+  // as well as in the "Biosample.bio_characteristics" attribute.
+  // For querying all disease contexts related to an individual, therefore queries
+  // should cover ($in) [Individual.bio_characteristics OR Biosample.bio_characteristics].
+  repeated BioCharacteristic bio_characteristics = 9;
+
   // The :ref:`ISO 8601<metadata_date_time>` time at which this Individual's record
   // was created.
   string created = 5;
@@ -46,9 +57,19 @@ message Individual {
   //   sex : { term_id: "PATO:0020000", term : "female genetic sex" }
   OntologyTerm sex = 8;
 
+  // The address coded as geolocation where this individual originated from.
+  // It is recommended that this reflects the place of birth or main place of
+  // living, not necessarily a current address.
+  GeoLocation location = 13;
+
   // A map of additional information regarding the Individual.
   Attributes attributes = 10;
 
+  // External identifiers representing this individual. These are considered
+  // different representation of the same record, not records which are in some
+  // other relation with the record at hand.
+  repeated ExternalIdentifier external_identifiers = 11;
+
 }
 
 
@@ -77,14 +98,15 @@ message Biosample {
   // The "description" attributes should not contain any structured data.
   string description = 4;
 
-  // OntologyTerm describing the primary disease associated with this Biosample.
-  OntologyTerm disease = 5;
+  // characteristics object uses lists of BioCharacteristic objects to describe
+  // diseases, phenotypes, source ... associated with this BioSample.
+  repeated BioCharacteristic bio_characteristics = 5;
 
   // The :ref:`ISO 8601<metadata_date_time>` time at which this Biosample record
   // was created.
   string created = 6;
 
-  // The :ref:`ISO 8601<metadata_date_time>` time at which this Biosample record was 
+  // The :ref:`ISO 8601<metadata_date_time>` time at which this Biosample record was
   // updated.
   string updated = 7;
 
@@ -94,21 +116,36 @@ message Biosample {
   // A map of additional information about the Biosample.
   Attributes attributes = 10;
 
+  // External identifiers representing this biosample. These are considered
+  // different representation of the same record, not records which are in some
+  // other relation with the record at hand.
+  repeated ExternalIdentifier external_identifiers = 11;
+
   // An age object describing the age of the individual this biosample was
   // derived from at the time of collection. The Age object allows the encoding
   // of the age either as ISO8601 duraion or time interval (preferred), or
   // as ontology term object.
-  Age individual_age_at_collection = 11;
+  // Example:
+  //   "individual_age_at_collection": {
+  //     "age": "P12Y0M",
+  //     "age_class": {
+  //         "term": "Juvenile onset",
+  //         "term_id": "HP:0003621"
+  //     }
+  // },
+  Age individual_age_at_collection = 12;
+
+  // The address coded as GeoLocation where the biosample was collected.
+  GeoLocation location = 13;
 }
 
-
 // The age object permits both the (considered default) encoding of an age
 // value in ISO8601, with arbitrary granularity; and the representation of an
 // "age class" as qualitative ontology term.
 // If available, a quantitative value should be used & take precedence over the
 // age class, and class assignment should be performed at user/API level.
-
 message Age {
+
   // The :ref:`ISO 8601<metadata_date_time>` age of this object as ISO8601
   // duration or time intervals. The use of time intervals makes an additional
   // anchor unnecessary (i.e. DOB and age can be represented as start-anchored
@@ -117,9 +154,65 @@ message Age {
   string age = 1;
 
   // An age class, e.g. corresponding to the use of "age of onset" in HPO.
-  // HPO is recommended, for example, subclasses of
+  // HPO is recommended, for example, subclasses of "Onnset":
   // http://purl.obolibrary.org/obo/HP_0003674
   // Example:
   //  age_class : { term_id : "HP:0003596", term : "Middle age onset" }
   OntologyTerm age_class = 2;
 }
+
+// BioCharacteristic is a prototype wrapper object for single instances
+// of phenotypes, diseases ... which may be described through one or several
+// ontology terms
+message BioCharacteristic {
+  // A free text description of the specific disease diagnosis or phenotype
+  // here, which is then characterized by zero or more OntologyTerm objects.
+  // The description should be concise and should not include data points
+  // better expressed through specific attributes elsewhere in the schema.
+  // Example (for a single disease item):
+  //   "squamous cell carcinoma, base of tongue, stage 2"
+  string description = 1;
+
+  // The ontologyTerms attribute contains a list of zero (discouraged) or more
+  // OntologyTerm objects covering the characteristic (e.g. disease diagnosis,
+  // phenotype) reorted here.
+  // Example (for a single diagnosis "squamous cell carcinoma, base of tongue"):
+  //
+  //     term_id: "DOID:0050865",
+  //     term: "tongue squamous cell carcinoma",
+  //
+  //     term_id: "UBERON:0006919",
+  //     term: "tongue squamous epithelium",
+  //
+  //     term_id: "UBERON:0010033",
+  //     term: "posterior part of tongue",
+  //
+  repeated OntologyTerm ontology_terms = 2;
+
+  // negatedOntologyTerms are used to describe features which are explicitely
+  // not part of the BioCharacteristic.
+  // Example: For a phenotype
+  //
+  //      description: "Bilateral ventricle anomalies (but not hypertrophy)"
+  //
+  //   ...  one could use the ontologyTerms
+  //
+  //      term_id: "HP:0001711"
+  //      term: "Abnormality of the left ventricle"
+  //
+  //      id: "HP:0001707"
+  //      term: "Abnormality of the right ventricle"
+  //
+  //   ... and add to negatedOntologyTerms
+  //
+  //      term_id: "HP:0001714"
+  //      term: "Ventricular hypertrophy"
+  //
+  repeated OntologyTerm negated_ontology_terms = 3;
+
+  // Logical scope of this BioCharacteristic. Typical examples
+  // could be "phenotype", "disease", "observation", "source".
+  // TODO:  This may be modified into an enumeration or expressed through
+  //        an OntologyTerm.
+  string scope  = 4;
+}