Complete encoder docstrings #3579

rhyolight · 2017-05-02T17:53:06Z

Complete

…ings

marionleborgne

👍 Nice doc. I have a couple of minor comments, mostly about RST styling.

marionleborgne · 2017-05-02T22:59:24Z

docs/source/api/algorithms/encoders.rst

+.. autoclass:: nupic.encoders.sdrcategory.SDRCategoryEncoder
+   :show-inheritance:
+
+Scalar Encoders
 ^^^^^^^^^^^^^^


Minor: Add missing ^. The RST linter complains ¯_(ツ)_/¯

marionleborgne · 2017-05-02T23:05:22Z

src/nupic/encoders/base.py

-     implemented by leaf encoders. Returns :class:`nupic.data.fieldmeta.FieldMetaType`.XXXXX
-     (e.g., :class:`nupic.data.fieldmeta.FieldMetaType`.float)
+     implemented by leaf encoders. Returns :class:`~nupic.data.field_meta.FieldMetaType`.XXXXX
+     (e.g., :class:`~nupic.data.field_meta.FieldMetaType`.float)
  - :func:`~nupic.encoders.base.Encoder.getWidth` - returns the output width, in
     bits


Consider using a backslash to indicate that the line continues. It escapes the newline character instead of breaking the block in the HTML rendering. Examples:

Before:

After:

Edits in nupic/encoders/base.py to fix the newline issue (I just added trailing \'s where needed):

class Encoder(object): """ An encoder converts a value to a sparse distributed representation. This is the base class for encoders that are compatible with the OPF. The OPF requires that values can be represented as a scalar value for use in places like the SDR Classifier. .. note:: The Encoder superclass implements: - :func:`~nupic.encoders.base.Encoder.encode` - returns a numpy array \ encoding the input; syntactic sugar on top of encodeIntoArray. If pprint, \ prints the encoding to the terminal. - :func:`~nupic.encoders.base.Encoder.pprintHeader` - prints a header \ describing the encoding to the terminal. - :func:`~nupic.encoders.base.Encoder.pprint` - prints an encoding to the \ terminal. .. warning:: The following methods and properties must be implemented by \ subclasses: - :func:`~nupic.encoders.base.Encoder.getDecoderOutputFieldTypes` - must be \ implemented by leaf encoders. \ Returns :class:`~nupic.data.field_meta.FieldMetaType`.XXXXX \ (e.g., :class:`~nupic.data.field_meta.FieldMetaType`.float) - :func:`~nupic.encoders.base.Encoder.getWidth` - returns the output width, \ in bits. - :func:`~nupic.encoders.base.Encoder.encodeIntoArray` - encodes input and \ puts the encoded value into the numpy output array, which is a 1-D array \ of length returned by :func:`~nupic.encoders.base.Encoder.getWidth`. - :func:`~nupic.encoders.base.Encoder.getDescription` - returns a list of \ (name, offset) pairs describing the encoded output. """

Ref of a similar issue for another block type: http://stackoverflow.com/a/28328736

marionleborgne · 2017-05-02T23:24:23Z

src/nupic/encoders/base.py


-    TODO: when we switch to Python 2.7 or 3.x, use OrderedDict
+              TODO: when we switch to Python 2.7 or 3.x, use OrderedDict


There is a TODO extension that you might be interested in.

Ref 1: https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html#todo-extension
Ref 2: http://www.sphinx-doc.org/en/1.0.8/ext/todo.html

marionleborgne · 2017-05-02T23:26:01Z

src/nupic/encoders/base.py

    """
    raise NotImplementedError()


  def encodeIntoArray(self, inputData, output):
    """
    Encodes inputData and puts the encoded value into the numpy output array,
-    which is a 1-D array of length returned by getWidth().
+    which is a 1-D array of length returned by :meth:`.getWidth`.

    Note: The numpy output array is reused, so clear it before updating it.


Consider using .. note::

marionleborgne · 2017-05-02T23:27:11Z

src/nupic/encoders/base.py

-    of the arrays, and we should start our counting from 1 rather than 0
+    Copy one array to another, inserting blanks between fields (for display).
+    If ``leftpad`` is one, then there is a dummy value at element 0
+    of the arrays, and we should start our counting from 1 rather than 0.

    :param inarray: TODO: document


Do you want to keep the TODO: document that remain here and there?

I've asked @scottpurdy for help with this.

marionleborgne · 2017-05-02T23:27:44Z

src/nupic/encoders/base.py

-    of the inputData with the scalar value returned from topDownCompute() on a
-    top-down representation to evaluate prediction accuracy, for example.
+    of the inputData with the scalar value returned from :meth:`.topDownCompute`
+    on a top-down representation to evaluate prediction accuracy, for example.

    :param inputData: The data from the source. This is typically a object with


Typo: This is typically an object

rhyolight · 2017-05-03T00:20:57Z

Thanks @marionleborgne I will fix these up and merge.

rhyolight added 14 commits April 14, 2017 12:42

Partial encoder docs

ebf0e70

Merge branch 'master' of github.com:numenta/nupic into encoder-docstr…

2233025

…ings

Fixed wronge module name in docs

d484db5

Added EncoderResult docs and Encoder module

59b1e59

Full rst docstrings for Encoder

15f1a5f

category encoders docstrings

20b7fc9

coordinate and geo encoder docstrings

0ab4ef9

delta encoder docstrings

0ab9e9a

log encoder docstrings

ad70a9e

Update docs TODO and encoder index page

2bd583a

Added docstrings for multi-encoder

019982e

Added docstrings for pass-through-encoder

cb2b1f7

Added docstrings for sparse-pass-through-encoder

2662df9

Finished scalar encoder docstrings

d4f302a

rhyolight requested a review from marionleborgne May 2, 2017 19:14

marionleborgne approved these changes May 2, 2017

View reviewed changes

Little cleanup of encoder docs

669de75

rhyolight merged commit 7cbb4a0 into numenta:master May 3, 2017

rhyolight deleted the encoder-docstrings branch May 3, 2017 14:45

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Complete encoder docstrings #3579

Complete encoder docstrings #3579

rhyolight commented May 2, 2017 •

edited

Loading

marionleborgne left a comment

marionleborgne May 2, 2017

marionleborgne May 2, 2017

marionleborgne May 2, 2017

marionleborgne May 2, 2017

marionleborgne May 2, 2017

rhyolight May 3, 2017

marionleborgne May 2, 2017

rhyolight commented May 3, 2017


		TODO: when we switch to Python 2.7 or 3.x, use OrderedDict
		TODO: when we switch to Python 2.7 or 3.x, use OrderedDict

Complete encoder docstrings #3579

Complete encoder docstrings #3579

Conversation

rhyolight commented May 2, 2017 • edited Loading

marionleborgne left a comment

Choose a reason for hiding this comment

marionleborgne May 2, 2017

Choose a reason for hiding this comment

marionleborgne May 2, 2017

Choose a reason for hiding this comment

marionleborgne May 2, 2017

Choose a reason for hiding this comment

marionleborgne May 2, 2017

Choose a reason for hiding this comment

marionleborgne May 2, 2017

Choose a reason for hiding this comment

rhyolight May 3, 2017

Choose a reason for hiding this comment

marionleborgne May 2, 2017

Choose a reason for hiding this comment

rhyolight commented May 3, 2017

rhyolight commented May 2, 2017 •

edited

Loading