ga4gh/schemas — pull request #74 by lh3 (2014-05-31 03:56:37+00:00)
Title: Tentative proposal on replacing GADataset with GAProject and adding GASample

The objects are simple but the interpretation and the scope are complex. Please see the in-code comments for detailed explanation. I have not added methods or changed every related field. Let's see how far we go. If this PR gets rejected quickly, I will save some time.

In the following, I am giving some background.

Firstly, a sample "NA12878" means different things in different projects. In 1000g pilot1, it represents high-coverage WGS data. In 1000g exome sequencing sub-project, it represents targeted sequencing data. In ENCODE long RNA-seq project, it represents RNA-seq data. This means we have to "subdivide" a sample name NA12878. In the examples above, the combination of (NA12878,project) is almost always an unambiguous and meaningful unit. GASample is defined based on this observation. For this definition to work, I also have to clarify GAProject/GADataset, in particular requiring them to be disjoint.

Secondly, about the BioSample database. From my limited (if not mistaken) queries to the database, NCBI and EBI differ. They both introduce a hierarchy and share the leaf nodes, but the internal nodes are not shared. In NCBI, a BioSample object is recursive by itself. EBI on the other hand introduces a new BioSampleGroup object. The internal nodes are not exchangeable. Anyway, the shared leaf nodes are very specific. If we search NA12878 in EBI, we will get 58 BioSamples and 21 BioSampleGroups (I don't know who defines Groups). In NCBI, 275 BioSamples, some of which are internal nodes. Although both the proposed GASample and the leaf nodes of BioSample are specific, they still have different scopes. A BioSample may appear in multiple SRA studies/BioProjects (e.g. SAMN00001544), but I am treating such a BioSample as multiple GASamples. As a result, BioSample and GASample have a many-to-many relationship.

Thirdly, about sample name. Due to the complication in my first point, the BioSample database is reluctant to use a sample name NA12878. When we search for NA12878, it appears in all kinds of attributes such as "hapmap", "cell line" and even in full text. I *guess* this is partly why NCBI and EBI give very different results on the same query although they are supposed to share most of the primary data. I think users and data producers would more like to call their samples as NA12878, *within their projects*. In addition, I am sure many labs will submit a BAM with a sample name "tumor". This is fine as they are still distinguishable by project.

---

Personally, I'd like to add a GAProject::projectType, which may take a value WGS, TARGET, RNASEQ, CHIPSEQ, etc. I think this will greatly help me to pinpoint the right data. I have deferred it for now.

In addition, as we are talking about permissions in another thread, I also have an opinion on this topic. I think we should attach a GAPermission object to both GAProject and GASample with the GASample permission overriding GAProject when both are present.

The relationship between GAProject and the existing objects. Each GAProject is equivalent to a google dataset. Each SRA/ENA study can be considered a GAProject.