metadata_redo.avdl

@namespace("org.ga4gh.models")

/**
This protocol defines metadata used in the other GA4GH protocols.
[EAGLE: Needs a fuller description of the document in the header. What are the "other protocols"? Metadata for what?]
*/

protocol Metadata {

import idl "common.avdl";

/**
Observations are single measurements, which can be described through their type, value and unit,
as well as an associated dateTime value. This could be numerical values with a unit, or 
observations defined through ontologies.
*/
record Observation {

  string type;

	/**
[EAGLE: Observation.type - suggest union { OntologyTerm.id, string } to encourage Ontology terms, e.g. EFO_0004324, body height
add an example of a measurement, e.g. body height, body weight, smoking behaviour.]
	*/
	
  string value;

	/**
	The unit of the observation; e.g. for numeric values.
	*/
  union { null, string } unit = null;

  /**
  Date the observation was made/assigned (e.g. date of diagnosis, observation of phenotype...).
  Suitable e.g. for health related purposes, epidemiology, experimental setups (time series) ...
  Format: ISO 8601, YYYY-MM-DDTHH:MM:SS (e.g. 2015-02-10T00:03:42Z)
  */
  union { null, timestamp-millis } dateTimeObserved = null;

  /**
  Age at time of the observation (e.g. diagnosis, observation of phenotype...).
  This is highly relevant in the human context and usually the primary available time related 
  parameter available.
  TODO: Unit? Years would be natural in human context.
  */
  union { null, timestamp-millis } ageObserved = null;
  
}

/**
A geolocation object, formatted as GeoJSON.
This simplified implementation supports the basic geometries 
of which "Point" and "Polygon" should represent the most likely 
use cases here (e.g. for description of a sample's provenience).
See also http://geojson.org/geojson-spec.html.
*/
record GeoLoc {

	string type;
	
	array<float> coordinates = [];

}

/**
An individual (or subject) typically corresponds to an individual
human or other organism.
*/
record Individual {

  /**
  The individual UUID. This is globally unique. 
  The recommendation is to use an anonymous UUID type with extremely low collision probability.
  The typical implementation would be UUIDv4.  
  This has to be provided by the implementation.
  */  
  string id;

  /** 
  The IDs of the different "ga4gh.Group"s this individual belongs to.
  Implementation dependent there may be the preference to keep the ids of "ga4gh.Individual", 
  "ga4gh.Sample" and so on inside the "ga4gh.Group" objects.
  */
  array<string> memberOf = [];
  
  /** 
  The IDs of "upstream" records of which this ga4ghObject is derived from. Examples for an annotated 
  record of type "experiment" would be e.g. UUIDs of the individual and sample type records it was 
  based on. Probably does not apply the "Individual" record type (use "memberOf" instead for families 
  etc.).
  Together with creation time stamps, this can also be part of a versioning concept where records of 
  the same type point towards their history.
  TODO: Alternatively use a "sameAs" attribute for records describing the same object w/ edits.
  */
  array<string> derivedFrom = [];

  /** 
  The IDs of "downstream" objects of which derive from this ga4ghObject. Examples for an annotated 
  object of type "individual" would be e.g. UUIDs of "sample" and "experiment" type objects.
  */
  array<string> parentOf = [];

  /**
  The name of the individual.
  This is for information purposes only and not expected to be used for identification purposes 
  or to be exposed at all across repositories. Also, no format is imposed though the recommendation 
  would be natural English language based - FirstName (middle components)? LastName.
  */
  union { null, string } name = null;

  /**
  For information purposes only. An optional, free text description of the individual. 
  */
  union { null, string } description = null;

  /**
  The time at which this individual's record was created. 
  Format: ISO 8601, YYYY-MM-DDTHH:MM:SS.SSS (e.g. 2015-02-10T00:03:42.123Z)
  */
  union { null, timestamp-millis } recordCreated = null;

  /**
  The time at which this individual's record was last updated.
  Format: ISO 8601, YYYY-MM-DDTHH:MM:SS.SSS (e.g. 2015-02-10T00:03:42.123Z)
  */
  union { null, timestamp-millis } recordUpdated = null;

  /**
  The species of this individual. Using
  [NCBI taxonomy](http://www.ncbi.nlm.nih.gov/taxonomy) is recommended.
  For a representation of an NCBI Taxon ID as an OntologyTerm, see
  [NCBITaxon Ontology](http://www.obofoundry.org/wiki/index.php/NCBITaxon:Main_Page).
  For example, 'Homo sapiens' has the ID 9606. The NCBITaxon ontology ID for this is
  NCBITaxon:9606, which has the URI http://purl.obolibrary.org/obo/NCBITaxon_9606
  */
  union { null, OntologyTerm } species = null;

  /**
  The genetic sex of this individual.
  */
+  union { null, OntologyTerm } sex = null;

  /**
  The developmental stage of this individual. Using Uberon is recommended.
  */
  union { null, OntologyTerm } developmentalStage = null;

  /**
  The date of birth of this individual as ISO 8601, YYYY-MM-DD format (e.g. 2008-08-18).
  The date may be fuzzed for privacy reasons.
  */
  union { null, date } dateOfBirth = null;

  /**
  Diseases with which the individual has been diagnosed.
  TODO: Usage disorders or diseases ...
  */
  array<OntologyTerm> disorders = [];

  /**
  Phenotypes for this individual.
  */
  array<OntologyTerm> phenotypes = [];

  /**
  Observation/measurements for this individual.
  */
  array<Observation> observations = [];

  /**
  Procedures for this individual.
  Examples could be cell line treatments (e.g. drug exposure with time series information), or 
  medical procedures performed on an individual.
  TODO: Explore ontologies for this.
  */
  array<OntologyTerm> procedures = [];

  /**
  The strain of this individual, for non-humans.
  */
  union { null, OntologyTerm } strain = null;

  /**
  A map of additional individual information.
  */
  map<array<string>> info = {};
[EAGLE: suggestion of further fields for this record: ethnicity, date of death, address?]
[EAGLE: Possibly abstract to a “Characteristics” type, similar to ‘Observation’? That would make the model more flexible and encourage the use of ontology terms, e.g. EFO for sex.]
[EAGLE: Data in this section (name and data of birth) require considerations with regards to the confidentiality and integrity of ePHI (electronic Personal Health Information) in transit. Overlap with the security working group here.]
}


/**
A biological sample used in an experiment. (e.g. whole blood from
an affected individual)
Only attributes occurring first at this object level are annotated (with the exception of the 
required ones).
*/
record Sample {

  string id;

  array<string> derivedFrom = [];

  array<string> parentOf = [];

  array<string> memberOf = [];

  /**
  Public identifiers for this sample. These could be database specific ids (think GEO "GSM12345") 
  or stable links.  
  */
  array<string> accessions = [];

  union { null, string } name = null;

  union { null, string } description = null;

  union { null, timestamp-millis } recordCreated = null;

  union { null, timestamp-millis } recordUpdated = null;

  /**
  The time at which this sample was taken.
  Format: ISO 8601, YYYY-MM-DDTHH:MM:SS (e.g. 2015-02-10T00:03:42Z)
  */
  union { null, timestamp-millis } samplingDateTime = null;

  /**
  The age of the individual (not of the sample) at time of sample collection.
  This field may be approximate.
  TODO: Unit? Years would be natural in human context.
  */
  union { null, long } ageAtSampling = null;

  /**
  The cell type of this sample.
  Using the [Cell Ontology](http://cellontology.org/) (CL) is recommended. See 
  */
  union { null, OntologyTerm } cellType = null;

  /** 
  The cell line of this sample. 
  Using the [Cell Line Ontology](https://code.google.com/p/clo-ontology/) is a possibility.
  TODO: discuss further. Other possibilities: Cellosaurus (nextprot), BRENDA/BTO, EFO (EBI)
  */
  union { null, OntologyTerm } cellLine = null;

  union { null, GeoLoc } geoloc = null;

  /**
  A descriptor of the sample type. (e.g. `frozen tissue`)
  */
  union { null, string } sampleType = null;

  /**
  The anatomical part of the individual from which this sample derives.
  Using [Uberon](http://uberon.org) is recommended.
  */
  union { null, OntologyTerm } organismPart = null;

  array<Observation> observations = [];

  map<array<string>> info = {};
  
}

/**
An experimental preparation of a `Sample`.
TODO: Either we make this "sequencingExperiment", or we exclude technology specific attribute names. 
There are many attributes which are specific to the current way to do genome analysis (e.g. 
"platformUnit").
*/
record Experiment {

  string id;

  union { null, string } name = null;

  union { null, string } description = null;

  union { null, timestamp-millis } recordCreated = null;

  union { null, timestamp-millis } recordUpdated = null;

  /**
  The time at which this experiment was performed.
  Format: ISO 8601, YYYY-MM-DDTHH:MM:SS (e.g. 2015-02-10T00:03:42Z)
  */
  union { null, timestamp-millis } runDate = null;

  /**
  The molecule examined in this experiment. (e.g. genomic DNA, total RNA)
  */
  union { null, string } molecule = null;

  /**
  The experiment technique or strategy applied to the sample.
  (e.g. whole genome sequencing, RNA-seq, RIP-seq)
  */
  union { null, string } strategy = null;

  /**
  The method used to enrich the target. (e.g. immunoprecipitation, size
  fractionation, RNase digestion)
  */
  union { null, string } selection = null;

  /**
  The name of the library used as part of this experiment.
  */
  union { null, string } library = null;

  /** The configuration of sequenced reads. (e.g. Single or Paired) */
  union { null, string } libraryLayout = null;

  /**
  The instrument model used as part of this experiment. This maps to sequencing technology in BAM.
  */
  union { null, string } instrumentModel;

  /**
  The data file generated by the instrument.
  TODO: This isn't actually a file is it? Should this be `instrumentData` instead?
  */
  union { null, string } instrumentDataFile = null;

  /**
  The analysis center used as part of this experiment.
  TODO: Again, specific for sequencing. Should be technology agnostic (who knows?).  
  */
  union { null, string } analysisCenter;

  /**
  The platform unit used as part of this experiment. This is a flowcell-barcode
  or slide unique identifier.
  TODO: Too specific?
  */
  union { null, string } platformUnit = null;

  array<Observation> observations = [];

  map<array<string>> info = {};

}

/**
Represents a group of individuals. (e.g. a trio or a cohort).
*/
record IndividualGroup {

  string id;

  union { null, string } name = null;

  union { null, string } description = null;

  union { null, timestamp-millis } recordCreated = null;

  union { null, timestamp-millis } recordUpdated = null;

  /**
  The type of individual group.
  TODO: Rethink this; could be a simple label static vs. dynamic; but then one may have to provide 
  an attribute containing the parameters (e.g. a query).
  */
  union { null, string } type = null;

  array<string> derivedFrom = [];

  map<array<string>> info = {};

}

/**
An analysis contains an interpretation of one or several experiments.
(e.g. SNVs, copy number variations, methylation status) together with
information about the methodology used.
*/
record Analysis {

  string id;

  union { null, string } name = null;

  union { null, string } description = null;

  union { null, timestamp-millis } recordCreated = null;

  union { null, timestamp-millis } recordUpdated = null;

  union { null, string } type = null;

  /**
  The software run to generate this analysis.
  */
  array<string> software = null;

  /**
  A map of interpreted analysis data.
  TODO: This is probably not the right format; has to be discussed.
  */
  map<array<string>> results = {};
  
  map<array<string>> info = {};

}

}