clean up docs, update concept info, add equivalence documentation. fixes

 #114

docs/ReadMe.html

@@ -302,7 +302,7 @@
   <a href="usage.html">
     <span class="glyphicon glyphicon-list"></span>
 
-    Using Usagi
+    Using the Application Functions
   </a>
 </li>
       </ul>
@@ -337,11 +337,11 @@ <h1 class="title toc-ignore">Documentation readme</h1>
 <h2>Contribute</h2>
 <p>Contributions to this documentation are very welcome and even a must when new features are implemented. To update the documentation, edit one of the following markdown files or create a new markdown file:</p>
 <ul>
-<li><a href="https://github.com/ohdsi/usagi/blob/master/docs/index.md">index.md</a></li>
-<li><a href="https://github.com/ohdsi/usagi/blob/master/docs/usage.md">usage.md</a></li>
-<li><a href="https://github.com/ohdsi/usagi/blob/master/docs/installation.md">installation.md</a></li>
+<li><a href="https://github.com/ohdsi/usagi/blob/master/docs/index.md" target="_blank">index.md</a></li>
+<li><a href="https://github.com/ohdsi/usagi/blob/master/docs/usage.md" target="_blank">usage.md</a></li>
+<li><a href="https://github.com/ohdsi/usagi/blob/master/docs/installation.md" target="_blank">installation.md</a></li>
 </ul>
-<p>The configuration of the page can be found in <a href="https://github.com/ohdsi/usagi/blob/master/docs/_site.yml">_site.yml</a>.</p>
+<p>The configuration of the page can be found in <a href="https://github.com/ohdsi/usagi/blob/master/docs/_site.yml" target="_blank">_site.yml</a>.</p>
 </div>
 <div id="render-html" class="section level2">
 <h2>Render html</h2>

docs/_site.yml

@@ -16,7 +16,7 @@ navbar:
     - text: "Installation & Setup"
       icon: glyphicon-save
       href: installation.html
-    - text: "Using Usagi"
+    - text: "Using the Application Functions"
       icon: glyphicon-list
       href: usage.html
   # chevron-last-down

docs/index.html

@@ -302,7 +302,7 @@
   <a href="usage.html">
     <span class="glyphicon glyphicon-list"></span>
 
-    Using Usagi
+    Using the Application Functions
   </a>
 </li>
       </ul>
@@ -335,10 +335,10 @@
 <p><img src="images/usagi_logo.png" /></p>
 <div id="introduction" class="section level1">
 <h1>Introduction</h1>
-<p>Usagi is a software tool created by the Observational Health Data Sciences and Informatics (OHDSI) team and is used to help in the process of mapping codes from a source system into the standard terminologies stored in the Observational Medical Outcomes Partnership (OMOP) Vocabulary (<a href="http://www.ohdsi.org/data-standardization/vocabulary-resources/" class="uri">http://www.ohdsi.org/data-standardization/vocabulary-resources/</a>). The word Usagi is Japanese for rabbit and was named after the first mapping exercise it was used for; mapping source codes used in a Japanese dataset into OMOP Vocabulary concepts.</p>
+<p>Usagi is a software tool created by the Observational Health Data Sciences and Informatics (OHDSI) team and is used to help in the process of mapping codes from a source system into the standard terminologies stored in <a href="http://www.ohdsi.org/data-standardization/vocabulary-resources/">the Observational Medical Outcomes Partnership (OMOP) Vocabulary</a>. The word Usagi is Japanese for rabbit and was named after the first mapping exercise it was used for; mapping source codes used in a Japanese dataset into OMOP Vocabulary concepts.</p>
 <p>Mapping source codes into the OMOP Vocabulary is valuable for two main reasons:</p>
 <ol style="list-style-type: decimal">
-<li>When converting a raw dataset into the OMOP Common Data Model (CDM) (<a href="http://www.ohdsi.org/data-standardization/the-common-data-model/" class="uri">http://www.ohdsi.org/data-standardization/the-common-data-model/</a>), translating source specific codes into standard concepts (i.e. RxNorm or SNOMED) translates the source data into a “common language” other CDMs follow.</li>
+<li>When converting a raw dataset into <a href="http://www.ohdsi.org/data-standardization/the-common-data-model/">the OMOP Common Data Model (CDM)</a>, translating source specific codes into standard concepts (i.e. RxNorm or SNOMED) translates the source data into a “common language” other CDMs follow.</li>
 <li>Having source codes tied into the OMOP Vocabulary concepts allow a researcher to leverage the power of finding relevant source codes leveraging classification terminologies in the OMOP Vocabulary (e.g. find all antipsychotic medications or find all condition codes related to heart failure).</li>
 </ol>
 </div>

docs/installation.html

@@ -11,7 +11,7 @@
 
 
 
-<title>Installation &amp; Setup</title>
+<title>Usagi - Installation &amp; Setup</title>
 
 <script src="site_libs/header-attrs-2.5/header-attrs.js"></script>
 <script src="site_libs/jquery-1.11.3/jquery.min.js"></script>
@@ -378,7 +378,7 @@
   <a href="usage.html">
     <span class="glyphicon glyphicon-list"></span>
 
-    Using Usagi
+    Using the Application Functions
   </a>
 </li>
       </ul>
@@ -410,15 +410,35 @@ <h1 class="title toc-ignore">Installation &amp; Setup</h1>
 
 
 <p><img src="images/usagi_logo.png" /></p>
-<div id="installation-and-support" class="section level1">
-<h1>Installation and support</h1>
-<p>All source code and installation instructions are available on Usagi’s GitHub site: <a href="https://github.com/OHDSI/Usagi" class="uri">https://github.com/OHDSI/Usagi</a></p>
-<p>Any bugs/issues/enhancements should be posted to the GitHub repository: <a href="https://github.com/OHDSI/Usagi/issues" class="uri">https://github.com/OHDSI/Usagi/issues</a></p>
-<p>Any questions/comments/feedback/discussion can be posted on the OHDSI Developer Forum: <a href="http://forums.ohdsi.org/c/developers" class="uri">http://forums.ohdsi.org/c/developers</a></p>
+<div id="installation" class="section level1">
+<h1>Installation</h1>
+<p>Usagi is a stand-alone java application, which requires Java 1.8 or higher to be installed. Java can be downloaded from <a href="http://www.java.com" target="_blank">java.com</a>.</p>
+<p>To get the latest Usagi build, download “Usagi_vx.x.x.jar” under the <a href="https://github.com/OHDSI/Usagi/releases/latest" target="_blank">Releases</a> tab.</p>
+<p>After downloading, Usagi can be started simply by double clicking the jar file. Alternatively, Usagi can be opened from the commandline: <code>java -jar Usagi_vx.x.x.jar</code>.</p>
 </div>
 <div id="one-time-setup" class="section level1">
-<h1>One-time setup</h1>
-<p><em>TBD</em></p>
+<h1>One-time Setup</h1>
+<p>The first time you start Usagi, you will be prompted to index the vocabularies. Usagi does not come with the indexes, you have to provide the vocabulary files. To do so, follow the folllowing steps:</p>
+<ol style="list-style-type: decimal">
+<li>Get the latest version of the vocabulary from <a href="http://athena.ohdsi.org">Athena</a>. An account is required. You can select any vocabularies that you need.</li>
+<li>When your vocabulary package is ready, download it and unzip the package.</li>
+<li>Open Usagi as described above.</li>
+<li>When prompted, specify the location of the downloaded vocabulary files to create the index.<br />
+The creation of the vocabulary index is a computationally expensive process and can take hours to complete.</li>
+<li>When finished, the vocabulary version should be displayed in the bottom right. Statistics of your index can be viewed from <em>Help</em> –&gt; <em>Show index statistics</em></li>
+</ol>
+<p><img src="images/index_stats.png" /></p>
+<p>When switching to a new version of Usagi, the index files can be copied over. Multiple versions of Usagi can even use the same index. The Usagi jar file and the index files just need to be in the same folder.</p>
+<p>In some cases, Usagi will not be able find the vocabulary index or the index creation becomes stuck after a few hours (see <a href="https://github.com/OHDSI/Usagi/issues/64">issue #64</a>). In both cases, opening Usagi from the commandline might help: <code>java -jar Usagi_vx.x.x.jar</code>.</p>
+</div>
+<div id="support" class="section level1">
+<h1>Support</h1>
+<p>All source code and installation instructions are available on Usagi’s GitHub site:<br />
+<a href="https://github.com/OHDSI/Usagi" class="uri">https://github.com/OHDSI/Usagi</a></p>
+<p>Any bugs/issues/enhancements should be posted to the GitHub repository:<br />
+<a href="https://github.com/OHDSI/Usagi/issues" class="uri">https://github.com/OHDSI/Usagi/issues</a></p>
+<p>Any questions/comments/feedback/discussion can be posted on the OHDSI Developer Forum:<br />
+<a href="http://forums.ohdsi.org/c/developers" class="uri">http://forums.ohdsi.org/c/developers</a></p>
 </div>
 
 

docs/installation.md

@@ -1,19 +1,50 @@
 ---
-pagetitle: "Installation & Setup"
+pagetitle: Usagi - Installation & Setup
 title: "Installation & Setup"
 ---
 
 ![](images/usagi_logo.png)
 
-# Installation and support
+# Installation
+Usagi is a stand-alone java application, which requires Java 1.8 or higher to be installed.
+Java can be downloaded from <a href="http://www.java.com" target="_blank">java.com</a>.
 
-All source code and installation instructions are available on Usagi’s GitHub site:
+To get the latest Usagi build, download "Usagi_vx.x.x.jar" under the <a href="https://github.com/OHDSI/Usagi/releases/latest" target="_blank">Releases</a> tab.
+
+After downloading, Usagi can be started simply by double clicking the jar file.
+Alternatively, Usagi can be opened from the commandline: `java -jar Usagi_vx.x.x.jar`.
+
+# One-time Setup
+
+The first time you start Usagi, you will be prompted to index the vocabularies.
+Usagi does not come with the indexes, you have to provide the vocabulary files.
+To do so, follow the folllowing steps:
+
+1. Get the latest version of the vocabulary from [Athena](http://athena.ohdsi.org). An account is required. You can select any vocabularies that you need.
+2. When your vocabulary package is ready, download it and unzip the package.
+2. Open Usagi as described above.
+2. When prompted, specify the location of the downloaded vocabulary files to create the index. \
+   The creation of the vocabulary index is a computationally expensive process and can take hours to complete.
+3. When finished, the vocabulary version should be displayed in the bottom right. 
+   Statistics of your index can be viewed from _Help_ --> _Show index statistics_ 
+
+![](images/index_stats.png)
+
+When switching to a new version of Usagi, the index files can be copied over.
+Multiple versions of Usagi can even use the same index.
+The Usagi jar file and the index files just need to be in the same folder.
+
+In some cases, Usagi will not be able find the vocabulary index or
+the index creation becomes stuck after a few hours (see [issue #64](https://github.com/OHDSI/Usagi/issues/64)).
+In both cases, opening Usagi from the commandline might help: `java -jar Usagi_vx.x.x.jar`.
+
+# Support
+
+All source code and installation instructions are available on Usagi’s GitHub site: \
 https://github.com/OHDSI/Usagi
 
-Any bugs/issues/enhancements should be posted to the GitHub repository:
+Any bugs/issues/enhancements should be posted to the GitHub repository: \
 https://github.com/OHDSI/Usagi/issues
 
-Any questions/comments/feedback/discussion can be posted on the OHDSI Developer Forum: http://forums.ohdsi.org/c/developers
-
-# One-time setup
-_TBD_
+Any questions/comments/feedback/discussion can be posted on the OHDSI Developer Forum: \
+http://forums.ohdsi.org/c/developers

docs/readme.md

@@ -10,11 +10,11 @@ output:
 Contributions to this documentation are very welcome and even a must when new features are implemented.
 To update the documentation, edit one of the following markdown files or create a new markdown file:
 
- - [index.md](https://github.com/ohdsi/usagi/blob/master/docs/index.md)
- - [usage.md](https://github.com/ohdsi/usagi/blob/master/docs/usage.md)
- - [installation.md](https://github.com/ohdsi/usagi/blob/master/docs/installation.md)
+ - <a href="https://github.com/ohdsi/usagi/blob/master/docs/index.md" target="_blank">index.md</a>
+ - <a href="https://github.com/ohdsi/usagi/blob/master/docs/usage.md" target="_blank">usage.md</a>
+ - <a href="https://github.com/ohdsi/usagi/blob/master/docs/installation.md" target="_blank">installation.md</a>
 
-The configuration of the page can be found in [_site.yml](https://github.com/ohdsi/usagi/blob/master/docs/_site.yml). 
+The configuration of the page can be found in <a href="https://github.com/ohdsi/usagi/blob/master/docs/_site.yml" target="_blank">_site.yml</a>. 
 
 ## Render html
 To generate the site from markdown files, run the following R script with the `./docs` folder as working directory.