Merge pull request #153 from cthoyt-forks-and-packages/package-cli

Move Selene CLI from an external script to within the package

Author: kathyxchen

README.md

@@ -51,10 +51,6 @@ If you would like to locally install Selene, you can run
 python setup.py install
 ```
 
-### Additional dependency for the CLI
-
-Please install `docopt` before running the command-line script `selene_cli.py` provided in the repository.
-
 ## About Selene
 
 Selene is composed of a command-line interface and an API (the `selene-sdk` Python package). 

docs/source/overview/cli.md

@@ -1,5 +1,8 @@
 # Selene CLI operations and outputs
-Selene provides a command-line interface (CLI) that takes in a user-specified configuration file containing the operations the user wants to run and the parameters required for these operations. (See [Operations](#operations) for more detail.)
+Selene provides a command-line interface (CLI) that takes in a user-specified configuration file containing the operations the user wants to run and the parameters required for these operations.
+It is automatically installed using a setuptools entrypoint so it can be called with the bash function
+`selene_sdk` from anywhere in the bash. It can also be called with `python -m selene_sdk`.
+See [Operations](#operations) for more detail.
 
 The sections that follow describe in detail how the various components that make up the configuration file are specified. For operation-specific sections (e.g. training, evaluation), we also explain what the expected outputs are.
 
@@ -54,7 +57,7 @@ Note that there should not be any commas at the end of these lines.
 - `random_seed`: Set a random seed for `torch` and `torch.cuda` (if using CUDA-enabled GPUs) for reproducibility.
 - `output_dir`: The output directory to use for all operations. If no `output_dir` is specified, Selene assumes that the `output_dir` is specified in all relevant function-type values for operations in Selene. (More information on what function-type values are in [later sections](#a-note-for-the-following-sections).) We recommend using this parameter for `train` and `evaluate` operations. 
 - `create_subdirectory`: If True, creates a directory within `output_dir`   with the name formatted as `%Y-%m-%d-%H-%M-%S`---the date/time when Selene was run. (This is only applicable if `output_dir` has been specified.)
-- `lr`:  The learning rate. If you use our [CLI script](https://github.com/FunctionLab/selene/blob/master/selene_cli.py), you can pass this in as a command-line argument rather than having it specified in the configuration file. 
+- `lr`:  The learning rate. If you use the CLI (`selene_sdk`), you can pass this in as a command-line argument rather than having it specified in the configuration file. 
 - `load_test_set`: This is only applicable if you have specified `ops: [train, evaluate]`. You can set this parameter to True (by default it is False and the test set is only loaded when training ends) if you would like to load the test set into memory before training begins---and therefore save the test data generated by a sampler to a .bed file. You would find this useful if you want to save a test dataset (see [Samplers used for training](#samplers-used-for-training-and-evaluation-optionally)) and you do not know if your model will finish training and evaluation within the allotted time that your job is run. You should also be running Selene on a machine that can support such an increase in memory usage (on the order of GBs, depending on how many classes your model predicts, how large the test dataset is, etc.). 
 
 ## Model architecture

selene-cpu.yml

@@ -6,6 +6,7 @@ channels:
   - conda-forge
 dependencies:
   - cython=0.29.3
+  - click==7.1.2
   - docopt=0.6.2
   - h5py=2.9.0
   - matplotlib=2.0.2

selene-gpu-snapshot.yml

@@ -97,6 +97,7 @@ dependencies:
   - pytorch=1.0.1=py3.6_cuda10.0.130_cudnn7.4.2_2
   - torchvision=0.2.2=py_3
   - pip:
+    - click==7.1.2
     - pkginfo==1.4.2
     - requests-toolbelt==0.8.0
     - torch==1.0.1.post2

selene-gpu.yml

@@ -7,6 +7,7 @@ channels:
 - defaults
 dependencies:
 - cython=0.29.3
+- click==7.1.2
 - docopt=0.6.2
 - h5py=2.9.0
 - pandas=0.20.3

selene_cli.py

@@ -0,0 +1,11 @@
+"""Entrypoint module, in case you use `python -m selene_sdk`.
+
+Why does this file exist, and why __main__? For more info, read:
+ - https://www.python.org/dev/peps/pep-0338/
+ - https://docs.python.org/3/using/cmdline.html#cmdoption-m
+"""
+
+from .cli import main
+
+if __name__ == '__main__':
+    main()

selene_sdk/__main__.py

@@ -0,0 +1,31 @@
+"""Command line interface for Selene.
+
+Why does this file exist, and why not put this in ``__main__``? You might be tempted to import things from ``__main__``
+later, but that will cause problems--the code will get executed twice:
+
+- When you run ``python3 -m selene_sdk`` python will execute``__main__.py`` as a script. That means there won't be any
+  ``selene_sdk.__main__`` in ``sys.modules``.
+- When you import __main__ it will get executed again (as a module) because
+  there's no ``selene_sdk.__main__`` in ``sys.modules``.
+
+.. seealso:: http://click.pocoo.org/5/setuptools/#setuptools-integration
+"""
+
+import click
+
+from selene_sdk import __version__
+from selene_sdk.utils import load_path, parse_configs_and_run
+
+
+@click.command()
+@click.version_option(__version__)
+@click.argument('path', type=click.Path(exists=True, file_okay=True, dir_okay=False))
+@click.option('--lr', type=float, help='If training, the optimizer learning rate', show_default=True)
+def main(path, lr):
+    """Build the model and trains it using user-specified input data."""
+    configs = load_path(path, instantiate=False)
+    parse_configs_and_run(configs, lr=lr)
+
+
+if __name__ == "__main__":
+    main()

selene_sdk/cli.py

@@ -50,6 +50,7 @@
       cmdclass=cmdclass,
       install_requires=[
         "cython>=0.27.3",
+        'click',
         "h5py",
         "matplotlib>=2.2.3",
         "numpy",
@@ -63,4 +64,10 @@
         "seaborn",
         "statsmodels",
         "torch>=0.4.1, <=1.4.0",
-    ])
+    ],
+    entry_points={
+        'console_scripts': [
+            'selene_sdk = selene_sdk.cli:main',
+        ],
+    },
+)