From c8f351aa0ae64ab43b075af6984032c87f42df2c Mon Sep 17 00:00:00 2001
From: Stephen <stephen@nowhere>
Date: Sat, 7 Jul 2018 00:00:00 +0000
Subject: [PATCH] Added program documentation

---
 README.md                       |  70 ++++++++++++++++++++++++++++++++
 demo/hiv1-genomes.zip           | Bin 0 -> 12635 bytes
 demo/hiv1-lanl.yml              |  53 ++++++++++++++++++++++++
 {samples => demo}/settings.yml  |   6 +--
 kameris/__init__.py             |   2 +-
 kameris/__main__.py             |   3 +-
 kameris/schemas/file_urls.json  |  32 +++++++++++----
 kameris/subcommands/classify.py |   2 +-
 kameris/utils/download_utils.py |   9 +++-
 9 files changed, 160 insertions(+), 17 deletions(-)
 create mode 100644 demo/hiv1-genomes.zip
 create mode 100644 demo/hiv1-lanl.yml
 rename {samples => demo}/settings.yml (88%)

diff --git a/README.md b/README.md
index b419e36..030ffed 100644
--- a/README.md
+++ b/README.md
@@ -32,6 +32,76 @@
     </a>
 </p>
 
+## Installing
+
+There are three ways to install this software. Choose whichever one is best for your needs:
+
+**1. If you already have Python 2.7 or 3.4+ installed (recommended):**
+
+Run `pip install kameris`.
+
+**2. If you do not have Python installed or are unable to install software:**
+
+[Click here](https://github.com/stephensolis/kameris/releases/latest) and download the version corresponding to your operating system.
+If you use Linux or macOS, you may need to run `chmod +x "path to downloaded program"`.
+
+**3. If you are a developer or want to build your own version of Kameris:**
+
+Clone this repository then run `make install`.
+
+## Quick demo
+
+This software is able to train sequence classification models and use them to make predictions.
+
+Before following these instructions, make sure you've installed the software.
+If you followed option **1** above and the command `kameris` doesn't work for you, try using `python -m kameris` instead.
+If you followed option **2** above and downloaded an executable, replace `kameris` in the instructions below with the name of the executable you downloaded.
+
+### Classifying sequences with an existing model
+
+First, let's classify some HIV-1 sequences.
+
+1. Start by downloading this zip file containing HIV-1 genomes, and extract it to a folder: https://raw.githubusercontent.com/stephensolis/kameris/master/demo/hiv1-genomes.zip.
+2. Run `kameris classify hiv1-mlp "path to extracted files"`
+
+This will output the top subtype match for each sequence and write all results to a new file `results.json`.
+
+The `hiv1-mlp` model is able to give class probabilities and a ranked list of predictions, but some models are only able to report the top match. For example, try `kameris classify hiv1-linearsvm "path to extracted files"`
+
+To see other available models, go to https://github.com/stephensolis/kameris-experiments/tree/master/models.
+
+### Training a new model
+
+Now, let's train our own HIV-1 sequence classification models.
+
+1. Create an empty folder and open a terminal in the folder.
+2. Create folders `data` and `output`.
+3. Run `kameris run-job https://raw.githubusercontent.com/stephensolis/kameris/master/demo/hiv1-lanl.yml https://raw.githubusercontent.com/stephensolis/kameris/master/demo/settings.yml`
+
+Depending on your computer's performance and internet speed, it may take 5-10 minutes to run.
+This will automatically download the required datasets and train a simpler version of the [hiv1/lanl-whole experiment from kameris-experiments](https://github.com/stephensolis/kameris-experiments).
+This was the exact job used to train the models from the previous section, and these are the same models used in the paper ["An open-source k-mer based machine learning tool for fast and accurate subtyping of HIV-1 genomes"](https://www.biorxiv.org/content/early/2018/07/05/362780).
+
+Now, open `output/hiv1-lanl-whole`. You will notice folders were created for each value of `k`. Within each folder are several files:
+- `fasta` contains the FASTA files extracted from the downloaded dataset used for model training and evaluation.
+- `metadata.json` contains metadata on the FASTA files used to determine the class for each sequence.
+- `cgrs.mm-repr` contains feature vectors for each sequence. See the mentioned paper for more technical details.
+- `classification-kmers.json` contains evaluation results after using cross-validation on the dataset. See the mentioned paper for more technical details.
+- The `.mm-model` files contain trained models which may be passed to `kameris classify` in order to classify new sequences. **Note** that models trained using Python 2 will not run under Python 3 and vice-versa.
+- `log.txt` is a log file containing all the output printed during job execution.
+- `rerun-experiment.yml` is a file which may be passed to `kameris run-job` in order to re-run the job and obtain exactly the files found in this directory.
+
+Kameris also includes functionality to summarize results in easy-to-read tables. Try it by running `kameris summarize output/hiv1-lanl-whole`.
+
+You can change the settings used to train the model: first download the files [hiv1-lanl.yml](https://raw.githubusercontent.com/stephensolis/kameris/master/demo/hiv1-lanl.yml) and [settings.yml](https://raw.githubusercontent.com/stephensolis/kameris/master/demo/settings.yml).
+Training settings are found in `hiv1-lanl.yml` -- try changing the value of `k` or uncommenting different classifier types.
+File storage and logging settings are found in `settings.yml`.
+After making changes, run `kameris run-job hiv1-lanl.yml settings.yml` to train your model.
+
+[//]: # (## Documentation)
+
+## Dependencies
+
 This project uses:
 
 - [stephensolis/kameris-backend](https://github.com/stephensolis/kameris-backend) to generate k-mer count vectors and distance matrices
diff --git a/demo/hiv1-genomes.zip b/demo/hiv1-genomes.zip
new file mode 100644
index 0000000000000000000000000000000000000000..0c7ab89bc89833ff78ddb1155a8d959c356305d3
GIT binary patch
literal 12635
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

literal 0
HcmV?d00001

diff --git a/demo/hiv1-lanl.yml b/demo/hiv1-lanl.yml
new file mode 100644
index 0000000..aaaf423
--- /dev/null
+++ b/demo/hiv1-lanl.yml
@@ -0,0 +1,53 @@
+name: hiv1-lanl-whole
+
+experiments:
+  subtype:
+    expand_options:
+      k: 5..6
+    min_group_pts: 18
+    include_recombinants: true
+    dataset:
+      archive: hiv1
+      archive_folder: lanl-whole
+      metadata: hiv1-lanl-whole
+    selection_key: subtype
+    groups: |
+      lambda options, metadata:
+        import collections
+        counts = collections.Counter(x[options['selection_key']] for x in metadata)
+        return {v: {'selection_key': options['selection_key'], 'values': [v]} for v in counts if v and counts[v] >= options['min_group_pts']}
+
+steps:
+  - type: select
+    copy_for_options: [k]
+    pick_group: |
+      lambda metadata, group_options, options:
+        return [x for x in metadata if (options['include_recombinants'] or not x['recombinant']) and
+                                       x[group_options['selection_key']] in group_options['values']]
+
+  - type: kmers
+    output_file: cgrs.mm-repr
+    mode: frequencies
+    k: from_options
+    bits_per_element: 16
+
+  - type: classify
+    features_file: cgrs.mm-repr
+    output_file: classification-kmers.json
+    validation_count: 10
+    classifiers:
+      #- 10-nearest-neighbors
+      #- nearest-centroid-mean
+      #- nearest-centroid-median
+      #- logistic-regression
+      #- sgd
+      - linear-svm
+      #- quadratic-svm
+      #- cubic-svm
+      #- decision-tree
+      #- random-forest
+      #- adaboost
+      #- gaussian-naive-bayes
+      #- lda
+      #- qda
+      - multilayer-perceptron
diff --git a/samples/settings.yml b/demo/settings.yml
similarity index 88%
rename from samples/settings.yml
rename to demo/settings.yml
index 91d932b..0b89704 100644
--- a/samples/settings.yml
+++ b/demo/settings.yml
@@ -2,11 +2,11 @@
 # this is required
 local_dirs:
   # the directory containing zipped datasets
-  archives: /data/archives
+  archives: data
   # the directory containing JSON metadata files
-  metadata: /data/metadata
+  metadata: data
   # the directory for storage of job output
-  output: /data/output
+  output: output
 
 # if desired, specifies an external service to use for logging
 # this is optional
diff --git a/kameris/__init__.py b/kameris/__init__.py
index 33d6f14..60df6c4 100644
--- a/kameris/__init__.py
+++ b/kameris/__init__.py
@@ -1,3 +1,3 @@
 from __future__ import unicode_literals
 
-__version__ = '0.6.dev1'
+__version__ = '1.0.0'
diff --git a/kameris/__main__.py b/kameris/__main__.py
index 4042fcb..ff62356 100644
--- a/kameris/__main__.py
+++ b/kameris/__main__.py
@@ -44,7 +44,8 @@ def main():
     except Exception as e:
         log = logging.getLogger('kameris')
         message = 'an unexpected error occurred: {}: {}'.format(
-            type(e).__name__, e.message or str(e)
+            type(e).__name__,
+            (e.message if hasattr(e, 'message') else '') or str(e)
         )
         if log.handlers:
             log.error(message)
diff --git a/kameris/schemas/file_urls.json b/kameris/schemas/file_urls.json
index 05ae68e..c4ff512 100644
--- a/kameris/schemas/file_urls.json
+++ b/kameris/schemas/file_urls.json
@@ -2,19 +2,33 @@
     "$schema": "http://json-schema.org/draft-04/schema#",
     "type": "object",
     "properties": {
-        "metadata": {"$ref": "#/definitions/url_list"},
-        "archives": {"$ref": "#/definitions/url_list"},
-        "models": {"$ref": "#/definitions/url_list"}
+        "metadata": {
+            "type": "object",
+            "additionalProperties": {"$ref": "#/definitions/url"}
+        },
+        "archives": {
+            "type": "object",
+            "additionalProperties": {"$ref": "#/definitions/url"}
+        },
+        "models": {
+            "type": "object",
+            "additionalProperties": {
+                "type": "object",
+                "properties": {
+                    "python2": {"$ref": "#/definitions/url"},
+                    "python3": {"$ref": "#/definitions/url"}
+                },
+                "additionalProperties": false,
+                "required": ["python2", "python3"]
+            }
+        }
     },
     "additionalProperties": false,
 
     "definitions": {
-        "url_list": {
-            "type": "object",
-            "additionalProperties": {
-                "type": "string",
-                "pattern": "http(s)?://.*"
-            }
+        "url": {
+            "type": "string",
+            "pattern": "http(s)?://.*"
         }
     }
 }
diff --git a/kameris/subcommands/classify.py b/kameris/subcommands/classify.py
index 72c2b63..6e08a7e 100644
--- a/kameris/subcommands/classify.py
+++ b/kameris/subcommands/classify.py
@@ -25,7 +25,7 @@ def run(args):
             model_url = args.model
         else:
             model_url = download_utils.url_for_file(args.model + '.mm-model',
-                                                    args.urls_file, 'model')
+                                                    args.urls_file, 'models')
         model_file = download_utils.open_url_cached(model_url, 'rb',
                                                     args.force_download)
 
diff --git a/kameris/utils/download_utils.py b/kameris/utils/download_utils.py
index 2d0a41f..9fcf909 100644
--- a/kameris/utils/download_utils.py
+++ b/kameris/utils/download_utils.py
@@ -8,6 +8,7 @@
 import requests
 from ruamel.yaml import YAML
 from six.moves import urllib
+import sys
 from tqdm import tqdm
 
 from . import defaults, fs_utils, job_utils
@@ -53,7 +54,11 @@ def url_for_file(path, urls_file, filetype):  # NOQA (cache line above)
         ))
 
     filename = os.path.splitext(os.path.basename(path))[0]
-    return urls[filetype][filename]
+    if filetype == 'models':
+        python_ver = 'python{}'.format(sys.version_info.major)
+        return urls[filetype][filename][python_ver]
+    else:
+        return urls[filetype][filename]
 
 
 def open_url_cached(url, mode, force_download=False):
@@ -63,7 +68,7 @@ def open_url_cached(url, mode, force_download=False):
                              'cache')
     fs_utils.mkdir_p(cache_dir)
 
-    cache_key = hashlib.md5(url).hexdigest()
+    cache_key = hashlib.md5(url.encode('utf-8')).hexdigest()
     cache_filename = os.path.join(cache_dir, cache_key)
     if not force_download and os.path.exists(cache_filename):
         log.info("file '%s' already downloaded, using cached version", url)