CLI Launch (#366)

* Scanpy engine now required

Without the --engine param we need to error if scanpy engine cannot be imported rather than waiting for all engines

* CLI options and help matches proposal

(but not all options hooked up yet)

* Flesh out top level args

* Move computation args to engine

* CLI input file (#374)

* Fix test command

(tests still won't work)

* Input is file instead of directory
- also renamed example file

* Csweaver/debug (#376)

* Respect debug flag for logging flask calls

* Add loading messages

* max categories (#377)

* Add max categories

* Rename max_categories to category_selection_limit

* ensure whole numbers

server/app/app.py

@@ -1,6 +1,6 @@
 import argparse
+import logging
 import os
-import warnings
 import webbrowser
 
 from flask import Flask
@@ -10,7 +10,7 @@ from flask_cors import CORS
 from flask_restful_swagger_2 import get_swagger_blueprint
 
 from .rest_api.rest import get_api_resources
-from .util.utils import Float32JSONEncoder
+from .util.utils import Float32JSONEncoder, whole_number
 from .web import webapp
 
 REACTIVE_LIMIT = 1_000_000
@@ -46,48 +46,112 @@ app.register_blueprint(
 app.add_url_rule("/", endpoint="index")
 
 
+def create_cli():
+    parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter)
+    parser.description = """
+synopsis:
+cellxgene <command> <data> [options]
+
+description:
+
+cellxgene is a local web application for exploring single cell expression.
+    """
+    parser.add_argument("-V", "--version", help="show version and exit")
+    subparsers = parser.add_subparsers(dest="program")
+    subparsers.required = True
+    launch_group = subparsers.add_parser("launch", help="launch web application",
+                                         formatter_class=argparse.RawTextHelpFormatter)
+    launch_group.description = """
+    cellxgene launches a local web application for exploring single cell expression data.
+
+    Data must be in a format that cellxgene expects [[ how to format ]]
+        """
+    launch_group.epilog = """
+    annotation names:
+    The data viewer requires a unique, human readable name for each observation and variable.  These are used for
+    various application features, such as the ability to view expression by gene. When launching cellxgene, appropriate
+    observation and variable annotations must be identified.
+
+    If --obs-name or --var-name parameters are specified, values in the named annotations will be used. If not
+    specified, the observation and variable index values will name each respectively.  An error will generated if the
+    values for each are not unique.
+
+    examples:
+    To run with the example dataset:
+
+        cellxgene example_dataset/pbmc3k.h5ad --title PBMC3K
+
+    To run with your own data with tsne layout:
+
+        cellxgene <your data file> --title <your title> -l tsne
+
+    To indicate that the human-readable variable annotation is named 'gene_names', and the human-readable observation
+    is 'cell_names':
+
+        cellxgene mydata.h5ad -var-name gene_names -obs-name cell_names
+
+        """
+    launch_group.add_argument("data", metavar="data", help="file containing the data to display")
+    launch_group.add_argument("--title", "-t", help="title to display -- if this is omitted the title will be the name "
+                                                    "of the data file.")
+    launch_group.add_argument(
+        "--listen-all",
+        help="bind to all interfaces (this makes the server accessible beyond this computer)",
+        action="store_true")
+    launch_group.add_argument("--port", help="port to run server on", type=int, default=5005)
+    launch_group.add_argument("--debug", action="store_true",
+                              help="more verbose output, including outputting warnings and every REST request")
+    launch_group.add_argument("--flask-debug", action="store_true", help=argparse.SUPPRESS)
+    launch_group.add_argument("--no-open", help="do not launch the webbrowser", action="store_false",
+                              dest="open_browser")
+    launch_group.add_argument(
+        "--category-selection-limit",
+        type=whole_number,
+        help="maximum number of categories to display on the front-end. "
+             "Annotations with more than this number are not displayed",
+        default=100)
+    try:
+        from .scanpy_engine.scanpy_engine import ScanpyEngine
+    except ImportError as e:
+        # We will handle more engines when they come
+        raise ImportError('Scanpy is required for cellxgene, please install scanpy and try again', e) from e
+    else:
+        ScanpyEngine.add_to_parser(launch_group)
+    return parser
+
+
 def run_scanpy(args):
     title = args.title
     if not title:
-        title = os.path.basename(os.path.normpath(args.data_directory))
-    api_base = f"http://127.0.0.1:{args.port}/api/"
-    app.config.update(
-        DATASET_TITLE=title,
-        CXG_API_BASE=api_base
-    )
-
-    from .scanpy_engine.scanpy_engine import ScanpyEngine
-    app.data = ScanpyEngine(args.data_directory, layout_method=args.layout, diffexp_method=args.diffexp)
+        file_parts = os.path.splitext(os.path.basename(args.data))
+        title = file_parts[0]
     if args.listen_all:
         host = "0.0.0.0"
     else:
         host = "127.0.0.1"
+    cellxgene_url = f"http://{host}:{args.port}"
+    api_base = f"{cellxgene_url}/api/"
+    app.config.update(
+        DATASET_TITLE=title,
+        CXG_API_BASE=api_base
+    )
+    if not args.debug:
+        log = logging.getLogger('werkzeug')
+        log.setLevel(logging.ERROR)
+    from .scanpy_engine.scanpy_engine import ScanpyEngine
+    print(f"Loading data from {args.data}")
+    app.data = ScanpyEngine(args.data, layout_method=args.layout, diffexp_method=args.diffexp,
+                            category_selection_limit=args.category_selection_limit)
+    print(f"Launching cellxgene")
     if args.open_browser:
-        webbrowser.open(f"http://{host}:{args.port}")
+        webbrowser.open(cellxgene_url)
+    print(f"Please go to {cellxgene_url}")
     app.run(host=host, debug=args.flask_debug, port=args.port)
 
 
 def main():
-    parser = argparse.ArgumentParser(description="Cellxgene is a tool for exploring single cell expression.")
-    parser.add_argument("--title", "-t", help="Title to display -- if this is omitted the title will be the name "
-                                              "of the directory from the data_directory arg")
-    parser.add_argument("--port", help="Port to run server on.", type=int, default=5005)
-    parser.add_argument("--flask-debug", action="store_true", help=argparse.SUPPRESS)
-    parser.add_argument("--no-open", help="Do not launch the webbrowser.", action="store_false", dest="open_browser")
-    parser.add_argument(
-        "--listen-all",
-        help="Bind to all interfaces (this makes the server accessible beyond this computer)",
-        action="store_true")
-    subparsers = parser.add_subparsers(dest="engine")
-    subparsers.required = True
-    try:
-        from .scanpy_engine.scanpy_engine import ScanpyEngine
-    except ImportError:
-        warnings.simplefilter('default', ImportWarning)  # Enable ImportWarning
-        warnings.warn("Scanpy engine not available", ImportWarning)
-    else:
-        ScanpyEngine.add_to_parser(subparsers, run_scanpy)
-    if len(subparsers.choices) == 0:
-        raise ImportError('Could not import any engines, see warnings above')
+    parser = create_cli()
     args = parser.parse_args()
-    args.func(args)
+    # TODO pick engine based on input file
+    print("cellxgene starting...\n")
+    run_scanpy(args)