Merge pull request #156 from kathyxchen/bugfixes-1020

Bugfixes 1020

Author: kathyxchen

docs/source/conf.py

@@ -37,7 +37,8 @@
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
     'sphinx.ext.napoleon',
-    'sphinx.ext.intersphinx']
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.autosectionlabel',]
 
 intersphinx_mapping = {
     'python': ('https://docs.python.org/', None),

docs/source/index.rst

@@ -16,8 +16,8 @@ The Github repository is located `here <https://github.com/FunctionLab/selene>`_
 
    overview/overview
    overview/installation
-   overview/tutorials
    overview/cli
+   overview/tutorials
    overview/faq
 
 .. toctree::

docs/source/overview/cli.md

@@ -0,0 +1,53 @@
+
+FAQ and additional resources
+============================
+
+Extending Selene
+----------------
+
+The main modules that users may want to extend are
+
+
+* ``selene_sdk.samplers.OnlineSampler``
+* ``selene_sdk.samplers.file_samplers.FileSampler``
+* ``selene_sdk.sequences.Sequence``
+* ``selene_sdk.targets.Target``
+
+Please refer to the documentation for these classes.
+If you are encounter a bug or have a feature request, please post to our Github `issues <https://github.com/FunctionLab/selene/issues>`_. E-mail [email protected] if you are interested in being a contributor to Selene.
+
+Join our `Google group <https://groups.google.com/forum/#!forum/selene-sdk>`_ if you have questions about the package, case studies, or model development.
+
+Exporting a Selene-trained model to Kipoi
+-----------------------------------------
+
+We have provided an example of how to prepare a model for upload to `Kipoi's model zoo <http://kipoi.org/>`_ using a model trained during case study 2. You can use `this example <https://github.com/FunctionLab/selene/tree/master/manuscript/case2/3_kipoi_export>`_ as a starting point for preparing your own model for Kipoi. We have provided a script that can help to automate parts of the process.
+
+We are also working on an export function that will be built into Selene and accessible through the CLI. 
+
+Hyperparameter optimization
+---------------------------
+
+Hyperparameter optimization is the process of finding the set of hyperparameters that yields an optimal model against a predefined score (e.g. minimizing a loss function). 
+Hyperparameters are the variables that govern the training process (i.e. these parameters are constant during training, compared to model parameters which are optimized/"tuned" by the training process itself). 
+Hyperparameter tuning works by running multiple trials of a single training run with different values for your chosen hyperparameters, set within some specified limit. Some examples of hyperparameters:
+
+
+* learning rate
+* number of hidden units
+* convolutional kernel size
+
+You can select hyperparameters yourself (manually) or automatically. 
+For automatic hyperparameter optimization, you can look into grid search or random search. 
+
+Some resources that may be useful:
+
+
+* `Hyperopt: Distributed Asynchronous Hyper-parameter Optimization <https://github.com/hyperopt/hyperopt>`_
+* `skorch: a scikit-learn compatible neural network library that wraps PyTorch <https://github.com/dnouri/skorch>`_
+* `Tune: scalable hyperparameter search <https://ray.readthedocs.io/en/latest/tune.html>`_
+* `Spearmint <https://github.com/JasperSnoek/spearmint>`_
+* `weights & biases <https://www.wandb.com/>`_
+* `comet.ml <https://www.comet.ml/>`_
+
+To use hyperparameter optimization on models being developed with Selene, you could implement a method that runs Selene (via a command-line call) with a set of hyperparameters and then monitors the validation performance based on the output to ``selene_sdk.train_model.validation.txt``. 

docs/source/overview/cli.rst

@@ -0,0 +1,61 @@
+
+Installation
+============
+
+Users can clone and build the repository locally or install Selene through conda/pip. 
+
+Please use Selene with Python 3.6+.
+
+Install `PyTorch <https://pytorch.org/get-started/locally/>`_. If you have an NVIDIA GPU, install a version of PyTorch that supports it---Selene will run much faster with a discrete GPU.
+
+Installing with Anaconda
+------------------------
+
+To install with conda (recommended for Linux users), run the following command in your terminal:
+
+.. code-block::
+
+   conda install -c bioconda selene-sdk
+
+Installing selene with pip:
+---------------------------
+
+.. code-block:: sh
+
+   pip install selene-sdk
+
+Note that we do not recommend pip-installing older versions of Selene (below 0.4.0), as these releases were less stable. 
+
+We currently only have a source distribution available for pip-installation. We are looking into releasing wheels in the future. 
+
+Installing from source
+----------------------
+
+Selene can also be installed from source.
+First, download the latest commits from the source repository:
+
+.. code-block::
+
+   git clone https://github.com/FunctionLab/selene.git
+
+The ``setup.py`` script requires NumPy, Cython, and setuptools. Please make sure you have these already installed.
+
+If you plan on working in the ``selene`` repository directly, we recommend `setting up a conda environment <https://conda.io/docs/user-guide/tasks/manage-environments.html#creating-an-environment-from-an-environment-yml-file>`_ using ``selene-cpu.yml`` or ``selene-gpu.yml`` (if CUDA is enabled on your machine) and activating it.
+
+Selene contains some Cython files. You can build these by running
+
+.. code-block:: sh
+
+   python setup.py build_ext --inplace
+
+If you would like to locally install Selene, you can run
+
+.. code-block:: sh
+
+   python setup.py install
+
+Additional dependency for running the CLI (versions 0.4.8 and below)
+--------------------------------------------------------------------
+
+Please install ``docopt`` before running the command-line script ``selene_cli.py`` provided in the repository. 
+In newer versions of Selene, the CLI can be run by calling ``python -m selene_sdk`` from anywhere in bash (assuming you have installed the library, through conda/pip/local install - ``python setup.py install``).