Merge pull request #96 from DoctorBud/typos-links-carousel

phenopackets.org website changes only...

Carousel, Typos, Draft Overview, More Links

I'm going to merge this after reviewing it briefly with @jmcmurry @kshefchek . It is generally an improvement and the best way to test it is to publish it to phenopackets.org to see it in action. We can move forward from here.

I disabled the partially written Overview content for now. Someone may wish to revisit the Overview content.

README.md

@@ -1,18 +1,38 @@
+# PhenoPackets
+
+[![](http:https://phenopackets.org/site/PhenoPackets_Logo.png)](http:https://phenopackets.org)
+
 [![Build Status](https://travis-ci.org/phenopackets/phenopacket-format.svg?branch=master)](https://travis-ci.org/phenopackets/patient-phenotype-submission-format)
-[![DOI](https://zenodo.org/badge/13996/phenopackets/phenopacket-format.svg)](https://zenodo.org/badge/latestdoi/13996/phenopackets/patient-phenotype-submission-format)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.46742.svg)](https://doi.org/10.5281/zenodo.46742) 
+
+
+## Overview
+
+PhenoPackets is an open standard for representing and sharing detailed descriptions of phenotypic abnormalities and characteristics of individual patients, organisms, diseases, and publications. This repository serves as the primary documentation about the PhenoPacket Exchange Format (PXF), including the JSON and YAML representations. Other repositories (see [Implementations](#implementations) below) contain Java, JavaScript, Python and other language-specific tools and implementations.
+
+### Motivation
+
+The health of an individual organism results from a complex interplay between its genes and environment. Although great strides have been made in standardizing the representation of genetic information for exchange, there are no comparable standards to represent phenotypes (e.g. patient symptoms and disease features) and environmental factors. Phenotypic abnormalities of individual organisms are currently described in diverse places and in diverse formats: publications, databases, health records, registries, clinical trials, and even social media. However, the lack of standardization, accessibility, and computability among these contexts makes it extremely difficult to effectively extract and utilize these data, hindering the understanding of genetic and environmental contributions to disease. 
 
-The health of an individual organism results from a complex interplay between its genes and environment. Although great strides have been made in standardizing the representation of genetic information for exchange, there are no comparable standards to represent phenotypes (e.g. patient symptoms and disease features) and environmental factors (Figure 1). Phenotypic abnormalities of individual organisms are currently described in diverse places and in diverse formats: publications, databases, health records, registries, clinical trials, and even social media. However, the lack of standardization, accessibility, and computability among these contexts makes it extremely difficult to effectively extract and utilize these data, hindering the understanding of genetic and environmental contributions to disease. 
 
 ## Documentation
 
-See the [Wiki](https://github.com/phenopackets/phenopacket-format/wiki/Getting-Started) for documentation
+See the [Phenopackets.org site](http:https://phenopackets.org) for the public-facing project documentation.
+
+Or, see the detailed Markdown-based [documentation](https://github.com/phenopackets/phenopacket-format/blob/master/docs/content/Overview.md) via GitHub.
+
+The [Wiki](https://github.com/phenopackets/phenopacket-format/wiki/Getting-Started) has additional documentation, although it may be out-of-date.
+
+## Implementations
 
-Or jump straight into the [reference implementation](https://github.com/phenopackets/phenopacket-reference-implementation)
+- [phenopacket-reference-implementation: Java Reference Implementation](https://github.com/phenopackets/phenopacket-reference-implementation).
+- [phenopackets-js: JavaScript Implementation](https://github.com/phenopackets/phenopackets-js).
+- [phenopacket-python: Python Implementation](https://github.com/phenopackets/phenopacket-python).
+- [pxftools: Command-line Utility for manipulating PhenoPackets](https://github.com/phenopackets/pxftools).
 
-## TODO
+## Contributing
 
-See the issue tracker for a complete list. Some of the main issues of relevance:
+The PhenoPackets standard is still evolving, and there are many opportunities to help, including improving the expressivity of the format and providing implementations that enable.
 
- * [#54](https://github.com/phenopackets/phenopacket-format/issues/54) - the examples in this repo may be out of date
- * [#55](https://github.com/phenopackets/phenopacket-format/issues/55) - JSON-schema is overly complex
+The [Issue Tracker](https://github.com/phenopackets/phenopacket-format/issues/) is a good start.
 

docs/README.md

@@ -1,23 +1,73 @@
-### About this `/docs` directory
+# About this `/docs` directory
 
-The contents of this directory are deployed via GitHub Pages.
+The contents of this directory are deployed via GitHub Pages as [http:https://phenopackets.org](http:https://phenopackets.org).
 
-The file `index.html` is primarily boilerplate HTML, with most of the actual
-web-visible content specified in Markdown files that are dynamically loaded and rendered in the browser.
+The CNAME file determines which site can legitimately redirect here.
+Currently, this is http:https://phenopackets.org. The CNAME in the master branch of
+this repo must correspond for the site to be viewable as GitHub pages.
 
+## Deployment structure
 
-#### Local Development
+Although the website appears seamless to a user, from an author's point of view
+there are two types of content, HTML and Markdown. These are divided into two
+directories, respectively: `/site` and `/content`. The goal behind this
+distinction is to encourage authors to improve and create content in Markdown,
+which is visible both through the fancy portal, as well as through the GitHub
+developer interface.
+
+### `index.html`
+
+The file `index.html` defines a basic marketing-style landing page with high-level content about PhenoPackets and several links to other aspects of the project, including the other PhenoPackets repositories. In addition, index.html has JavaScript that dynamically loads more detailed information from Markdown files, and optionally renders these Markdown files (if the user clicks the 'Details' buttons on the page).
+
+### Markdown content
+
+The directory `/content` contains several Markdown files that serve two purposes:
+
+- These files may be viewed directly via GitHub, providing a source of reusable documentation
+- The content of these files may be more easily edited than HTML
+
+
+## Editing and Adding Content
+
+The high-level content is within `index.html` and the detailed content is within the Markdown files in `/content`.
+
+### Editing index.html
+
+Please use two-column indentation and no tab stops. HTML is difficult to maintain if indentation is not uniform.
+
+Please test any changes on both narrow and wide screens. Ideally, use your browser's 'Responsive Design Mode' to allow you to see how the site looks on a mobile device.
+
+
+## Editing Markdown files
+
+It is important to realize that the same markdown files are rendered through the http:https://phenopackets.org site as well as through the GitHub portal. Relative image links from Markdown files in `/content' to image files in `/content` need to be specified with a relative prefix `![](./` as in the example below:
 
 ```
-cd phenopacket-format/
-http-server -c-1 docs/
+![](./phenopacket-ecosystem_2016-02-18a.png)
+```
+
+When the `index.html` page dynamically loads the Markdown content, the JavaScript code will *adjust* the prefix above to be `![](content/`so that the page can refer to the image file relative to index.html; it's a hack, but it works as long as Markdown authors use the above convention.
+
+
+## Local Testing
+
+It is necessary to run a local HTTP server to be able to try out the website effectively. I recommend `http-server`, which is easy to install and use if you already have a NodeJS environment:
+
+```
+npm install -g http-server
+```
+
+Once you have an HTTP server, it should be started so that it serves the `phenopacket-format/docs` directory as the website base URL `/`. In addition, caching should be disabled, so that local edits can be seen upon page refresh. For example, here is how to do this with `http-server`:
+
+
+```
+cd phenopacket-format/docs/
+http-server -c-1 .
 ```
 
 
 ### Credits
 
 - https://commons.wikimedia.org/wiki/File:DNA_com_GGN.jpg
-
 - [Start Bootstrap](http:https://startbootstrap.com/)
-
 - [Stylish Portfolio](http:https://startbootstrap.com/template-overviews/stylish-portfolio/)

docs/content/Community.md

@@ -1,10 +1,15 @@
 # Community
 
 Historically, successful standards evolve gradually over time. They are not designed in the abstract, springing fully-formed from committee, but rather are developed incrementally as they are taken into the field and proven to successfully meet real-world challenges. Level 1 of the PXF is intentionally simple in order to ease wide adoption of the standard and thereby increase the value of the network of systems (see Figure 1) aiming to share Phenopackets for computational use.
+
 The requirements for such a standard are:
+
 1. Computable. The standard must be both human and machine-interpretable, enabling computing operations and validation on the basis of defined relationships between diagnoses, lab measurements, genotypic information, and medications.
+
 2. Transferable. The standard must enable seamless transfer of data from a data source (e.g., a document describing the phenotype) to a data receiver (e.g., an application that receives and uses it). The standard can have multiple serializations, such as tab-separated-values, XML, or JSON.
+
 3. Utilize an ontology for phenotypes. The standard must enable “fuzzy matching”, that is, the use of algorithms that leverage the logic within an ontology to match sets of phenotypes that are related but not exact matches. This is currently mission critical for rare disease, and we believe will also greatly facilitate precision medicine.
+
 Journals can aid use of the PXF standard by supporting data citation to Phenopackets, essentially a metadata record, which will be made available as a separate online document resolvable by a Digital Object Identifier (DOI)18. Phenopackets can be deposited in the journal, a public phenotype data repository such as the Monarch Initiative, or in generic data repositories such as FigShare. This approach ensures that the phenotype data described within a manuscript is made computable outside the pay-wall of journals, and can be cited within the original article via the DOI. The PXF has been adopted as a recommended or mandatory standard by journals including the CSH Molecular Case Studies, the Orphanet Journal of Rare Disease, and XXX.
 
 It is hoped that public data repositories will begin to accept phenotype data provided in PXF. For example, the Monarch Initiative19 is already pulling Phenopacket data from the aforementioned journals and also provides an online editor tool for creating them. A variety of international efforts that aim to standardize genotype-phenotype data, such as the International Rare Diseases Research Consortium (IRDIRC) and the Global Alliance for Genomics and Health (GA4GH), support the use of this new PXF standard for sharing phenotypic data related to variant and other genomic health data.
@@ -14,6 +19,7 @@ It is hoped that public data repositories will begin to accept phenotype data pr
 # Discussion
 
 In many ways, the phenotype data exchange community is in a position similar to that of the genetics community in the early days of public sequence databases. Although the content of sequence descriptions has changed over the years, this evolution is a sign of success, not failure. Early descriptions played key roles both in promoting the effective use of sequence data and in understanding how that data should be recorded and communicated. The Phenopacket standard proposed here is tailored to function in the context of rare disease, and for precision medicine in cancer and other common diseases. We are currently in an exciting position and the standardization and exchange of a broad range of phenotype data can trigger a new wave of advances in medical discovery and realize the goal of precision medicine. Further, patient-centered phenotyping approaches offer the opportunity, if not the necessity, for affected individuals and their families to be involved and integrated into the wider context that is the future of precision medicine.
+
 The documentation and use of data for patients with challenging to diagnose rare and genetic conditions is different than for more common diseases. The realization of this vision and the phenotype exchange requirement described here will require substantial effort. Given the relative immaturity of existing efforts, further research and prototypes of data capture and exchange systems will be necessary to better understand the issues. Such explorations will likely be undertaken by ongoing research efforts, many which do not have the luxury of waiting for the completion of an emerging consensus model.