[add:docs] Add proper documentation (#40)

* Add proper documentation

* Remove and ignore docs/_build directory

.gitignore

@@ -58,6 +58,9 @@ coverage.xml
 .hypothesis/
 .pytest_cache/
 
+# Documentation
+docs/_build
+
 # Jupyter Notebook
 .ipynb_checkpoints
 

CHANGELOG.md

@@ -1,21 +1,21 @@
-# [0.2.0](https://github.com/eonu/sequentia/releases/tag/v0.2.0)
+## [0.2.0](https://github.com/eonu/sequentia/releases/tag/v0.2.0)
 
 #### Major changes
 - Add multi-processing support for `DTWKNN` predictions. ([#29](https://github.com/eonu/sequentia/pull/29))
 - Rename the `fit_transform()` function in `Preprocess` to `transform()` since there is nothing being fitted. ([#35](https://github.com/eonu/sequentia/pull/35))
-- Modify package classifiers in `setup.py`: ([#31](https://github.com/eonu/sequentia/pull/31))
+- Modify package classifiers in `setup.py` ([#31](https://github.com/eonu/sequentia/pull/31)):
   - Set development status classifier to `Pre-Alpha`.
   - Add Python version classifiers for v3.5+.
   - Specify UNIX and macOS operating system classifiers.
 
 #### Minor changes
 - Finish tutorial and example notebooks. ([#35](https://github.com/eonu/sequentia/pull/35))
 - Rename `examples` directory to `notebooks`. ([#32](https://github.com/eonu/sequentia/pull/32))
-- Host notebooks statically on [`nbviewer`](https://github.com/jupyter/nbviewer). ([#32](https://github.com/eonu/sequentia/pull/32))
+- Host notebooks statically on [nbviewer](https://github.com/jupyter/nbviewer). ([#32](https://github.com/eonu/sequentia/pull/32))
 - Add reference to Pomegranate [paper](http://jmlr.org/papers/volume18/17-636/17-636.pdf) and [repository](https://github.com/jmschrei/pomegranate). ([#30](https://github.com/eonu/sequentia/pull/30))
 - Add badges to `README.md`. ([#28](https://github.com/eonu/sequentia/pull/28))
 
-# [0.1.0](https://github.com/eonu/sequentia/releases/tag/v0.1.0)
+## [0.1.0](https://github.com/eonu/sequentia/releases/tag/v0.1.0)
 
 #### Major changes
 

README.md

@@ -1,19 +1,26 @@
+<h1 align="center">
+  <img src="https://i.ibb.co/42GkhfR/sequentia.png" width="275px" alt="Sequentia">
+</h1>
+
+<p align="center">
+  <em>A machine learning interface for isolated temporal sequence classification algorithms in Python.</em>
+</p>
+
 <div align="center">
-  <a href="https://pypi.org/project/sequentia/">
+  <a href="https://pypi.org/project/sequentia">
     <img src="https://img.shields.io/pypi/v/sequentia?style=flat-square" alt="PyPI"/>
   </a>
-  <a href="https://pypi.org/project/sequentia/">
+  <a href="https://pypi.org/project/sequentia">
     <img src="https://img.shields.io/pypi/pyversions/sequentia?style=flat-square" alt="PyPI - Python Version"/>
   </a>
   <a href="https://raw.githubusercontent.com/eonu/sequentia/master/LICENSE">
     <img src="https://img.shields.io/pypi/l/sequentia?style=flat-square" alt="PyPI - License"/>
   </a>
+  <a href="https://sequentia.readthedocs.io/en/latest">
+    <img src="https://readthedocs.org/projects/sequentia/badge/?version=latest&style=flat-square" alt="Read The Docs - Documentation">
+  </a>
 </div>
 
-# Sequentia
-
-_A machine learning interface for isolated temporal sequence classification algorithms in Python._
-
 ## Introduction
 
 <img src="https://i.ibb.co/gPymgs4/classifier.png" width="40%" align="right"></img>
@@ -44,7 +51,7 @@ Sequentia offers the use of **multivariate observation sequences with differing
 
 ### Preprocessing methods
 
-- [x] Normalization (centering observation sequences)
+- [x] Normalization
 - [x] Downsampling (by decimation and averaging)
 - [x] Discrete (Fast) Fourier Transform
 
@@ -60,6 +67,10 @@ Sequentia offers the use of **multivariate observation sequences with differing
 pip install sequentia
 ```
 
+## Documentation
+
+Documentation for the package is available on [Read The Docs](https://sequentia.readthedocs.io/en/latest).
+
 ## Tutorials and examples
 
 For tutorials and examples on the usage of Sequentia, [look at the notebooks here](https://nbviewer.jupyter.org/github/eonu/sequentia/tree/master/notebooks/)!
@@ -91,13 +102,13 @@ All contributions to this repository are greatly appreciated. Contribution guide
 	<thead>
 		<tr>
 			<th align="center">
-                <a href="/eonu">
-                <img src="https://avatars0.githubusercontent.com/u/24795571?s=460&v=4" alt="Edwin Onuonga" width="60px">
-                <br/><sub><b>Edwin Onuonga</b></sub>
-                </a>
-                <br/>
-                <a href="mailto:ed@eonu.net">✉️</a>
-                <a href="https://eonu.net">🌍</a>
+        <a href="/eonu">
+        <img src="https://avatars0.githubusercontent.com/u/24795571?s=460&v=4" alt="Edwin Onuonga" width="60px">
+        <br/><sub><b>Edwin Onuonga</b></sub>
+        </a>
+        <br/>
+        <a href="mailto:ed@eonu.net">✉️</a>
+        <a href="https://eonu.net">🌍</a>
 			</th>
 			<!-- Add more <th></th> blocks for more contributors -->
 		</tr>

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_includes/examples/classifiers/dtwknn.py

@@ -0,0 +1,13 @@
+import numpy as np
+from sequentia.classifiers import DTWKNN
+
+# Create some sample data
+X = [np.random.random((10 * i, 3)) for i in range(1, 4)]
+y = ['class0', 'class1', 'class1']
+
+# Create and fit the classifier
+clf = DTWKNN(k=1, radius=5)
+clf.fit(X, y)
+
+# Predict labels for the training data (just as an example)
+clf.predict(X)

docs/_includes/examples/classifiers/hmm.py

@@ -0,0 +1,11 @@
+import numpy as np
+from sequentia.classifiers import HMM
+
+# Create some sample data
+X = [np.random.random((10 * i, 3)) for i in range(1, 4)]
+
+# Create and fit a left-right HMM with random transitions and initial state distribution
+hmm = HMM(label='class1', n_states=5, topology='left-right')
+hmm.set_random_initial()
+hmm.set_random_transitions()
+hmm.fit(X)

docs/_includes/examples/classifiers/hmm_classifier.py

@@ -0,0 +1,21 @@
+import numpy as np
+from sequentia.classifiers import HMM, HMMClassifier
+
+# Create and fit some sample HMMs
+hmms = []
+for i in range(5):
+    hmm = HMM(label=f'class{i}', n_states=(i + 3), topology='left-right')
+    hmm.set_random_initial()
+    hmm.set_random_transitions()
+    hmm.fit([np.arange((i + j * 20) * 30).reshape(-1, 3) for j in range(1, 4)])
+    hmms.append(hmm)
+
+# Create some sample test data and labels
+X = [np.random.random((10 * i, 3)) for i in range(1, 4)]
+y = ['class0', 'class1', 'class1']
+
+# Create a classifier and calculate predictions and evaluations
+clf = HMMClassifier()
+clf.fit(hmms)
+predictions = clf.predict(X)
+accuracy, confusion = clf.evaluate(X, y)

docs/_includes/examples/preprocessing/downsample.py

@@ -0,0 +1,8 @@
+import numpy as np
+from sequentia.preprocessing import downsample
+
+# Create some sample data
+X = [np.random.random((10 * i, 3)) for i in range(1, 4)]
+
+# Downsample the data with downsample factor 5 and decimation
+X = downsample(X, n=5, method='decimate')

docs/_includes/examples/preprocessing/fft.py

@@ -0,0 +1,8 @@
+import numpy as np
+from sequentia.preprocessing import fft
+
+# Create some sample data
+X = [np.random.random((10 * i, 3)) for i in range(1, 4)]
+
+# Transform the data
+X = fft(X)

docs/_includes/examples/preprocessing/normalize.py

@@ -0,0 +1,8 @@
+import numpy as np
+from sequentia.preprocessing import normalize
+
+# Create some sample data
+X = [np.random.random((10 * i, 3)) for i in range(1, 4)]
+
+# Normalize the data
+X = normalize(X)

docs/_includes/examples/preprocessing/preprocess.py

@@ -0,0 +1,14 @@
+import numpy as np
+from sequentia.preprocessing import Preprocess
+
+# Create some sample data
+X = [np.random.random((10 * i, 3)) for i in range(1, 4)]
+
+# Create the Preprocess object
+pre = Preprocess()
+pre.normalize()
+pre.downsample(10, method='average')
+pre.fft()
+
+# Transform the data applying transformations in order
+X = pre.transform(X)

docs/changelog.rst

@@ -0,0 +1,6 @@
+.. _changelog:
+
+Changelog
+=========
+
+.. mdinclude:: ../CHANGELOG.md

docs/conf.py

@@ -0,0 +1,69 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+import sys
+import os
+import subprocess
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath('..'))
+
+subprocess.call('pip install numpydoc sphinx_rtd_theme m2r', shell=True)
+
+# -- Project information -----------------------------------------------------
+
+project = 'sequentia'
+copyright = '2019-2020, Edwin Onuonga'
+author = 'Edwin Onuonga'
+
+# The full version, including alpha/beta/rc tags
+release = '0.2.0'
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.viewcode',
+    'numpydoc',
+    'm2r'
+]
+
+autodoc_member_order = 'bysource'
+autosummary_generate = True
+numpydoc_show_class_members = False
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+source_suffix = ['.rst', '.md']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build']
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

docs/index.rst

@@ -0,0 +1,58 @@
+.. Sequentia documentation master file, created by
+   sphinx-quickstart on Sat Dec 28 19:22:34 2019.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+.. image:: https://i.ibb.co/42GkhfR/sequentia.png
+    :alt: Sequentia
+    :width: 275
+    :target: https://github.com/eonu/sequentia
+
+About
+=====
+
+Sequentia is a collection of machine learning algorithms for performing the classification of isolated temporal sequences.
+
+Each isolated sequence is generally modeled as a section of a longer multivariate time series
+that represents the entire sequence. Naturally, this fits the description of many types of problems such as:
+
+- isolated word utterance frequencies in speech audio signals,
+- isolated hand-written character pen-tip trajectories,
+- isolated hand or head gestures positions in a video or motion-capture recording.
+
+Most modern machine learning algorithms won't work directly out of the box when applied to such
+sequential data – mostly due to the fact that the dependencies between observations at different
+time frames must be considered, and also because each isolated sequence generally has a different duration.
+
+Sequentia offers some appropriate classification algorithms for these kinds of tasks.
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :caption: Sequentia
+
+   self
+   changelog.rst
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Classifiers and Models
+
+   sections/classifiers/hmm.rst
+   sections/classifiers/dtwknn.rst
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Preprocessing Methods
+
+   sections/preprocessing/normalize.rst
+   sections/preprocessing/downsample.rst
+   sections/preprocessing/fft.rst
+   sections/preprocessing/preprocessing.rst
+
+Documentation Search and Index
+==============================
+
+* :ref:`search`
+* :ref:`genindex`
+* :ref:`modindex`