Merge pull request #344 from Sage-Bionetworks/develop

Develop

Author: Kenneth Daily

CONTRIBUTING.md

@@ -0,0 +1,65 @@
+## About this project
+
+Welcome! This project is for managing annotations and controlled vocabularies for use in Synapse. These have been developed with communities supported by Sage Bionetworks in mind, but are not restricted to that use. If you want the files in your projects to be discoverable in the same fashion as the Sage-supported communities, then feel free to use these!
+
+## Contributing
+
+This contributing document focuses on the guidelines for users related to the Sage Bionetworks supported communities - that is to say Sage Bionetworks employees and members of the communities who are responsible for metadata and annotations.
+
+## Guidelines for proposing new terms
+
+Our strategy is to rely on annotation terms and definitions that have already been made and standardized whenever possible for use with Sage Bionetworks supported communities. In general, we will not include terms in this repository that are not needed and vetted by our communities - but don't let that stop you from using this! Feel free to fork and include terminology that you require for your own use.
+
+If you are proposing a new term, then we require a source for the definition. The first place to look for an existing term is the [EMBL-EBI Ontology Lookup Service](https://www.ebi.ac.uk/ols). We have some preferred ontology term sources: EDAM, EFO, OBI, and NCIT. It's OK if your term comes from another source, but use the preferred sources whenever possible. If your term does not currently exist, or has a different definition than existing ones, then:
+
+1. Provide a different source URL - this may be a Wikipedia entry, link to a commercial web site, or other URL.
+1. If you are a Sage Bionetworks employee and cannot find a source URL, then use "Sage Bionetworks" as the `source` and your own definition.
+2. If you are not (nor are you working with a Sage Bionetworks supported community) it is up to you for a strategy for controlling new terms to be added.
+
+## Guidelines for specific term types 
+
+In some situations (e.g. drug names), terms are not always well-captured by the ontologies found in the Ontology Lookup Service. We've defined some best practices for contributing these terms here.
+
+### Contribution of drug terms
+
+The preferred first-pass strategy for chemical name annotation is to search the EMBL-EBI ontology lookup service to find names, descriptions, and sources. Typically, the NCI Thesaurus will provide a suitable description for drugs and other biologically active molecules. In situations where the query molecule is not found in [EMBL-EBI Ontology Lookup Service](https://www.ebi.ac.uk/ols), a helpful secondary location to find chemical descriptions is [MeSH](https://meshb.nlm.nih.gov/).
+
+Example: 
+
+```
+{
+        "value": "DEFACTINIB",
+        "description": "An orally bioavailable, small-molecule focal adhesion kinase (FAK) inhibitor with potential antiangiogenic and antineoplastic activities.",
+        "source": "http://purl.obolibrary.org/obo/NCIT_C79809"
+},
+```
+
+In situations where novel molecules (such as newly-synthesized research compounds or proprietary pharmaceutical molecules) require annotation, the only suitable description and source might be the paper describing the synthesis or discovery, or information from the pharmaceutical company that created the identifier. 
+
+Example:
+
+```
+{
+        "value": "IPC-12345",
+        "description": "An small-molecule target of importance 4 (TOI4) inhibitor with potential antineoplastic activities.",
+        "source": "Important Pharma Company"
+},
+{
+        "value": "BestChemist-00913",
+        "description": "An investigational small molecule discovered by Best Chemist et al.",
+        "source": "PubMed Link Goes Here"
+},
+```
+
+
+## Contribution procedure
+
+Again, this is focused on Sage Bionetworks supported communities and employees. This focuses on the logistical components to contributing - for the technical components, please see the [Development](https://github.com/Sage-Bionetworks/synapseAnnotations#development) section of the [README.md](README.md) document.
+
+1. Propose a change, either through a Github [issue](https://github.com/Sage-Bionetworks/synapseAnnotations/issues) or [pull request](https://github.com/Sage-Bionetworks/synapseAnnotations/pulls). Your change should be as atomic as possible - e.g., don't lump together many unrelated changes into a single issue or pull request. You may be requested to split them out.
+1. Label your issue or pull request with the appropriate labels. For example, if you are suggesting a new value be added to an existing key, then `create value` would be the appropriate label.
+1. Assign the issue to yourself and anyone else who will be involved in completing it. At a minimum, the issue creator should be assigned initially.
+1. If this is a pull request a review from someone in Github - this can be found under 'Reviewers' on the right side of the screen when viewing a Github issue. It's fine if they can review your pull request without meeting. Otherwise, set up a meeting on your own to meet with your reviewer.
+1. If your reviewer has no problems with the change, then the change can be merged. 
+The issue creator is responsible for merging. Note that you can use [keywords](https://help.github.com/articles/closing-issues-using-keywords/) to close issues via your pull request. See the [Development](https://github.com/Sage-Bionetworks/synapseAnnotations#development) section of the [README.md](README.md) document for the merging procedure.
+1. If you and the reviewer decide that a larger discussion is necessary, the issue can be brought to the larger annotations working group for discussion.

README.md

@@ -1,17 +1,30 @@
 [![Build Status](https://travis-ci.org/Sage-Bionetworks/synapseAnnotations.svg?branch=master)](https://travis-ci.org/Sage-Bionetworks/synapseAnnotations)
 
+> Use our [Annotation UI](https://shiny.synapse.org/users/nsanati/annotationUI/) application to easily view and search our existing annotation definitions:
+>
+
 # Introduction
 
-Sage Bionetworks derived standards for annotating content in Synapse.
+Sage Bionetworks derived standards for annotating content in Synapse. This provide a mechanism for defining, managing, and implementing controlled vocabularies when annotating content in Synapse. The standards here are developed for Sage Bionetworks supported communities and consortiums by the [Sage Bionetworks Synapse Annotations working group](https://www.synapse.org/annotation) but are available for any other use.
+
+# Annotation definitions
 
-# Schemas
+This repository contains schemas that define the things we want to annotate as well as the controlled values that may be used. You can think of these as 'columns' of a table, each with a limited set of values that can occur in each column.
 
-Schemas are stored here in [Synapse Table Schema](http://docs.synapse.org/articles/tables.html) format. A schema is a list of [`Column Model`s](http://docs.synapse.org/rest/org/sagebionetworks/repo/model/table/ColumnModel.html) in JSON format.
+Our schema definitions are stored here in [Synapse Table Schema](http://docs.synapse.org/articles/tables.html) format. A schema is a list of [`Column Model`s](http://docs.synapse.org/rest/org/sagebionetworks/repo/model/table/ColumnModel.html) in JSON format. Using this format allows us to use them in a straightforward manner with other features of Synapse, including [file views](http://docs.synapse.org/articles/fileviews.html) and [tables](http://docs.synapse.org/articles/tables.html).
 
 Column types are required, and the valid types can be found [here](http://docs.synapse.org/rest/org/sagebionetworks/repo/model/table/ColumnType.html).
 
+# Organization
+
+All schema definitions can be found in the [synapseAnnotations/synapseAnnotations/data/](synapseAnnotations/synapseAnnotations/data/) folder. There are three high level schemas: [experimental data](synapseAnnotations/synapseAnnotations/data/experimentalData.json), [tool](synapseAnnotations/synapseAnnotations/data/tool.json), and [analysis](synapseAnnotations/synapseAnnotations/data/analysis.json).
+
+Schemas for specific communities and consortia are also defined, such as for the [neurodegenerative diseases consortiums](synapseAnnotations/data/neuro.json), [cancer consortiums](synapseAnnotations/data/cancer.json), and specific group such as (but not limited to) [Project GENIE](synapseAnnotations/data/genie.json).
+
 # Development
 
+This section discusses the technical steps for developing on this repository. See the [CONTRIBUTING.md](CONTRIBUTING.md) document for more information on how to contribute annotations to this project.
+
 Internal development can be performed by branching from `develop` to your own feature branch, making changes, pushing the branch to this repository, and opening a pull request. Pull requests against the `develop` branch require a review before merging. The only pull requests that will go to `master` are from `develop`, and will trigger a new release (see below for release procedures). If you are editing using the Github web site, make sure you switch to the `develop` branch first before clicking the `Edit this file` button. If you accidentally open a pull request against `master`, you can change this in your pull request using the `Edit` button.
 
 All pushed branches and pull requests are also tested through the continuous integration service [Travis CI](https://travis-ci.org/Sage-Bionetworks/synapseAnnotations). All JSON files are linted using [demjson's](deron.meranda.us/python/demjson/) `jsonlint` command line program.
@@ -33,37 +46,33 @@ pip install -r requirements.txt
 1. Make changes on your feature branch.
 1. Request and complete a review from someone on the team.
 1. When review is completed, note it to be reviewed and merged at the weekly meeting.
-1. Finalize merge into the `master` branch.
+1. Finalize merge into the `develop` branch.
 1. Update the version and make a versioned release (with assistance from @teslajoy)
 
 # Release Versioning Annotations
 Releases are made through Github tags and are available on the [Releases](https://github.com/Sage-Bionetworks/synapseAnnotations/releases) page.
 
-The release version structure **v0.0.0** follows [semantic versioning](http://semver.org/) guidelines. New releases are made using the following rules:
+The release version structure **vX.X.X** follows [semantic versioning](http://semver.org/) guidelines. New releases are made using the following rules:
 
-Major version **v0** increments by:
+Major version increments by:
 1. Changes in data structure (ex. yaml to json or json to mongodb)
 2. Changes to existing keys
 3. Changes to existing values
 
-Minor version **.0.** increments by: 
+Minor version increments by:
 1. Adding keys
 2. Adding values
 
-Patch version **.0** increments by: 
+Patch version increments by:
 1. Errors or corrections that don't break the API
 
-To optimize usability, the release tags should be placed on two required and one optional locations: 
-1. A Synapse Project annotation as a single value vs. list of versions and defined by the key **`annotationVersion`**. 
-2. The Shiny application [Annotation UI](https://github.com/Sage-Bionetworks/annotationUI)'s **title** 
+To optimize usability, the release tags should be placed on two required and one optional locations:
+1. A Synapse Project annotation as a single value defined by the key **`annotationReleaseVersion`**.
+2. The Shiny application [Annotation UI](https://github.com/Sage-Bionetworks/annotationUI)'s **title**
 3. OPTIONAL: Documented in a Synapse Project wiki.
 
-**Note:** _Git Commit messages including the words **added** or **changed** would facilitate the release version incrementation process_ 
-
 ## Update `CHANGELOG.md` and release notes
 
-After drafting a release, use this [Ruby package](https://github.com/skywinder/github-changelog-generator) to autogenerate a `CHANGELOG.md` locally that can be committed to the repository. It requires a Github Personal Access Token.
+After drafting a release, use this [Ruby package](https://github.com/skywinder/github-changelog-generator) to auto-generate a `CHANGELOG.md` locally that can be committed to the repository. It requires a [Github Personal Access Token](https://github.com/settings/tokens).
 
 ```
-
-

synapseAnnotations/data/analysis.json

@@ -276,7 +276,7 @@
   }, 
   {
     "name": "alignmentMethod", 
-    "description": "DNA or RNA sequence alignement method", 
+    "description": "DNA or RNA sequence alignment method", 
     "columnType": "STRING", 
     "maximumSize": 250, 
     "enumValues": [
@@ -384,11 +384,36 @@
     "columnType": "STRING", 
     "maximumSize": 250, 
     "enumValues": [
+      {
+        "value": "Variant calling",
+        "description": "Identify and map genomic alterations, including single nucleotide polymorphisms, short indels and structural variants, in a genome sequence.",
+        "source": "http://edamontology.org/operation_3227"
+      },
+      {
+        "value": "Sequence alignment",
+        "description": "Alignment of reads to a reference genome",
+        "source": "http://edamontology.org/operation_0292"
+      },
       {
         "value": "genotypeImputation", 
         "description": "The statistical inference of unobserved genotypes", 
         "source": ""
       }, 
+      {
+        "value": "DNAmethylationImputation", 
+        "description": "", 
+        "source": "https://dx.doi.org/10.1534/genetics.115.185967"
+      },
+      {
+        "value": "polygenicRiskScore",
+        "description": "A sample level estimate of the genetic component of disease risk based on genome-wide association studies",
+        "source": "http://journals.plos.org/plosgenetics/article?id=10.1371/journal.pgen.1003348"
+      },
+      {
+        "value": "Enrichment Analysis", 
+        "description": "Over-representation analysis", 
+        "source": "http://edamontology.org/operation_3501"
+      }, 
       {
         "value": "statisticalNetworkReconstruction", 
         "description": "", 
@@ -493,6 +518,56 @@
         "value": "peakCalling", 
         "description": "", 
         "source": ""
+      },
+      {
+        "value": "Copy number estimation",
+        "description": "Estimate the number of copies of loci of particular gene(s) in DNA sequences typically from gene-expression profiling technology based on microarray hybridisation-based experiments.",
+        "source": "http://edamontology.org/operation_3233"
+      },
+      {
+        "value": "Gene expression profile comparison",
+        "description": "Comparison of gene expression profiles.",
+        "source": "http://edamontology.org/operation_0315"
+      },
+      {
+        "value":"de-novo assembly",
+        "description": "",
+        "source": "http://purl.obolibrary.org/obo/GENEPIO_0001628"
+      },
+      {
+        "value":"correlation",
+        "description":"The degree to which two or more quantities or events are linearly associated, a statistical relation between two or more variables such that systematic changes in the value of one variable are accompanied by systematic changes in the others.",
+        "source":"http://purl.obolibrary.org/obo/NCIT_C48834"
+      },
+      {
+        "value":"network analysis",
+        "description":"A  data transformation that takes as input data that describes biological networks in terms of the node (a.k.a. vertex) and edge graph elements and their characteristics and generates as output properties of the constituent nodes and edges, the sub-graphs, and the entire network.",
+        "source":"http://purl.obolibrary.org/obo/OBI_0200080"
+      },
+      {
+        "value":"purity",
+        "description":"A quantitative assessment of the homogeneity or uniformity of a mixture. Alternatively, purity refers to the degree of being free of contaminants or heterogeneous components",
+        "source":"http://purl.obolibrary.org/obo/NCIT_C62352"
+      },
+      {
+        "value":"dose response study",
+        "description":"A study of the effect of dose changes on the efficacy of a drug in order to determine the dose-response relationship and optimal dose of a therapy.",
+        "source":"http://purl.obolibrary.org/obo/NCIT_C127803"
+      },
+      {
+        "value":"assessment",
+        "description":"The final result of a determination of the value, significance, or extent of.",
+        "source":"http://purl.obolibrary.org/obo/NCIT_C25217"
+      },
+      {
+        "value":"quality control",
+        "description":"A technique used to ensure a certain level of quality in a product or service.",
+        "source":"http://purl.obolibrary.org/obo/ERO_0001219"
+      },
+      {
+        "value":"comparison",
+        "description":"The examination of two or more people or things in order to detect similarities and differences.",
+        "source":"http://purl.obolibrary.org/obo/NCIT_C49156"
       }
     ]
   }, 
@@ -569,6 +644,11 @@
         "value": "GaussianProcessRegression", 
         "description": "", 
         "source": ""
+      },
+      {
+        "value": "elastic net",
+        "description": "Elastic net is a shrinkage and selection regression method that linearly combines the L1 and L2 penalties of the lasso and ridge methods.",
+        "source": "http://purl.enanomapper.org/onto/ENM_8000083"
       }
     ]
   },

synapseAnnotations/data/compoundScreen.json

@@ -518,5 +518,12 @@
         "columnType":"STRING",
         "maximumSize": 250,
         "enumValues": []
-    }
+    },
+    {
+      "name": "compoundDoseRange",
+      "description": "The minimum and maximum values of a treatment range; e.g. 1-25",
+      "columnType": "STRING",
+      "maximumSize": 250,
+      "enumValues": []
+  }
   ]