From c2993ab42dbd43a67ab2fe29e31e7f71c61ad047 Mon Sep 17 00:00:00 2001 From: Matthew Taylor Date: Thu, 13 Apr 2017 11:42:06 -0700 Subject: [PATCH] Fieldmeta docstrings (#3541) * Removed references to nupic.data.File * fieldmeta helpers docs * Removed duplicate data/fieldmeta docs --- docs/README.md | 8 +- docs/source/api/algorithms/encoders.rst | 11 --- docs/source/api/data/field-meta.rst | 13 +++ docs/source/api/data/index.rst | 6 ++ docs/source/api/index.rst | 1 + src/nupic/data/fieldmeta.py | 107 +++++++++++++++--------- 6 files changed, 90 insertions(+), 56 deletions(-) create mode 100644 docs/source/api/data/field-meta.rst create mode 100644 docs/source/api/data/index.rst diff --git a/docs/README.md b/docs/README.md index 221c1305f8..43368978dc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,6 +14,7 @@ sphinx-autobuild ${NUPIC}/docs/source ${NUPIC}/docs/_build_html \ List of NuPIC packages and their documentation status: * `TODO`: Package doc needs to be reviewed and potentially converted to RST * `OK`: Package RST doc reviewed and approved. +* `DEFER`: Would be nice to document, but not necessary for 1.0 ``` nupic @@ -24,10 +25,9 @@ nupic │   ├── sdr_classifier.py [OK] │   └── sdr_classifier_factory.py [OK] ├── data -│   ├── CategoryFilter.py [TODO] -│   ├── aggregator.py [TODO] -│   ├── dictutils.py [TODO] -│   ├── fieldmeta.py [TODO] +│   ├── aggregator.py [DEFER] +│   ├── dictutils.py [DEFER] +│   ├── fieldmeta.py [OK] │   ├── file_record_stream.py [TODO] │   ├── filters.py [TODO] │   ├── functionsource.py [TODO] diff --git a/docs/source/api/algorithms/encoders.rst b/docs/source/api/algorithms/encoders.rst index 747f3ca636..7b5aa88553 100644 --- a/docs/source/api/algorithms/encoders.rst +++ b/docs/source/api/algorithms/encoders.rst @@ -48,14 +48,3 @@ MultiEncoder .. autoclass:: nupic.encoders.multi.MultiEncoder :members: :show-inheritance: - -Data ----- - -FieldMetaType -^^^^^^^^^^^^^ - -.. autoclass:: nupic.data.fieldmeta.FieldMetaType - :members: - :private-members: - :undoc-members: diff --git a/docs/source/api/data/field-meta.rst b/docs/source/api/data/field-meta.rst new file mode 100644 index 0000000000..36f2b2d210 --- /dev/null +++ b/docs/source/api/data/field-meta.rst @@ -0,0 +1,13 @@ +Field Meta +========== + +.. automodule:: nupic.data.fieldmeta + +.. autoclass:: nupic.data.fieldmeta.FieldMetaInfo + :members: + +.. autoclass:: nupic.data.fieldmeta.FieldMetaType + :members: + +.. autoclass:: nupic.data.fieldmeta.FieldMetaSpecial + :members: diff --git a/docs/source/api/data/index.rst b/docs/source/api/data/index.rst new file mode 100644 index 0000000000..7ca99bb1e8 --- /dev/null +++ b/docs/source/api/data/index.rst @@ -0,0 +1,6 @@ +Data +---- + +Data wrappers and helpers. + +.. include:: field-meta.rst diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst index 6381d1cad8..fb46cd638c 100644 --- a/docs/source/api/index.rst +++ b/docs/source/api/index.rst @@ -29,4 +29,5 @@ together your own system with encoders and classifiers. opf/index network/index algorithms/index + data/index io diff --git a/src/nupic/data/fieldmeta.py b/src/nupic/data/fieldmeta.py index d1da0e6139..b134158036 100644 --- a/src/nupic/data/fieldmeta.py +++ b/src/nupic/data/fieldmeta.py @@ -19,10 +19,10 @@ # http://numenta.org/licenses/ # ---------------------------------------------------------------------- - -# This script defines the structure of meta-data that describes the field name, -# field type, special field attribute, etc. for a field in a dataset - +""" +This module defines the structure of meta-data that describes the field name, +field type, special field attribute, etc. for a field in a dataset. +""" from collections import namedtuple @@ -35,28 +35,29 @@ class FieldMetaInfo(FieldMetaInfoBase): """ This class acts as a container of meta-data for a single field (column) of - a dataset. - - The layout is backward-compatible with the tuples exposed via the 'fields' - attribute of the legacy nupic.data.file.File class (in file.py). However, the - elements may be accessed in a less error-prone and more self-documenting way - using object attribute notation (e.g., fieldmeta.special instead of - fieldmeta[2]). Because namedtuple creates a subclass of tuple, the elements - can also be accessed using list access semantics and operations (i.e., - fieldmeta[2]) + a dataset. Each instance of this class has ``name``, ``type``, and ``special`` + properties. Examples: 1. Access a sub-element from an instance of FieldMetaInfo: - metainfo.name - metainfo.type - metainfo.special - 2. Convert a single element from nupic.data.file.File.fields to FieldMetaInfo + - ``metainfo.name`` + - ``metainfo.type`` + - ``metainfo.special`` + + 2. Create a single element of ``FieldMetaInfo`` from a tuple of ``name``, + ``type``, and ``special``: + + .. code-block:: python + e = ('pounds', FieldMetaType.float, FieldMetaSpecial.none) m = FieldMetaInfo.createFromFileFieldElement(e) - 3. + :param str name: field name + :param str type: one of the values from FieldMetaType + :param str special: one of the values from FieldMetaSpecial + :raises ValueError: if type or special arg values are invalid """ @@ -64,12 +65,6 @@ def __init__(self, name, type, # pylint: disable=W0622 special): - """ - :param str name: field name - :param str type: one of the values from FieldMetaType - :param str special: one of the values from FieldMetaSpecial - :raises ValueError: if type or special arg values are invalid - """ if not FieldMetaType.isValid(type): raise ValueError('Unexpected field type %r' % (type,)) @@ -82,22 +77,40 @@ def __init__(self, @staticmethod def createFromFileFieldElement(fieldInfoTuple): - """ Creates a FieldMetaInfo instance from an element of the File.fields list - of a nupic.data.file.File class instance. + """ + Creates a :class:`.fieldmeta.FieldMetaInfo` instance from a tuple containing + ``name``, ``type``, and ``special``. + + :param fieldInfoTuple: Must contain ``name``, ``type``, and ``special`` + :return: :class:`~.fieldmeta.FieldMetaInfo` instance """ return FieldMetaInfo._make(fieldInfoTuple) @classmethod def createListFromFileFieldList(cls, fields): - """ Creates a FieldMetaInfo list from the File.fields value of a - nupic.data.file.File class instance. + """ + Creates a FieldMetaInfo list from the a list of tuples. Basically runs + :meth:`~.fieldmeta.FieldMetaInfo.createFromFileFieldElement` on each tuple. + + *Example:* - fields: a sequence of field attribute tuples conforming to the format - of the File.fields attribute of a nupic.data.file.File class instance. + .. code-block:: python - Returns: A list of FieldMetaInfo elements corresponding to the given - 'fields' list. + # Create a list of FieldMetaInfo instances from a list of File meta-data + # tuples + el = [("pounds", FieldMetaType.float, FieldMetaSpecial.none), + ("price", FieldMetaType.float, FieldMetaSpecial.none), + ("id", FieldMetaType.string, FieldMetaSpecial.sequence), + ("date", FieldMetaType.datetime, FieldMetaSpecial.timestamp), + ] + ml = FieldMetaInfo.createListFromFileFieldList(el) + + :param fields: a sequence of field attribute tuples conforming to the format + of ``name``, ``type``, and ``special`` + + :return: A list of :class:`~.fieldmeta.FieldMetaInfo` elements corresponding + to the given 'fields' list. """ return [cls.createFromFileFieldElement(f) for f in fields] @@ -105,7 +118,15 @@ def createListFromFileFieldList(cls, fields): class FieldMetaType(object): """ - Public values for the field data types + Public values for the field data types. Valid types are: + + - ``string`` + - ``datetime`` + - ``int`` + - ``float`` + - ``bool`` + - ``list`` + - ``sdr`` """ string = 'string' datetime = 'datetime' @@ -113,7 +134,7 @@ class FieldMetaType(object): float = 'float' boolean = 'bool' list = 'list' - sdr = 'sdr' # sparse distributed representation + sdr = 'sdr' _ALL = (string, datetime, integer, float, boolean, list, sdr) @@ -122,10 +143,9 @@ class FieldMetaType(object): def isValid(cls, fieldDataType): """Check a candidate value whether it's one of the valid field data types - :param str fieldDataType: candidate field data type + :param fieldDataType: (string) candidate field data type :returns: True if the candidate value is a legitimate field data type value; - False if not - :rtype: bool + False if not """ return fieldDataType in cls._ALL @@ -133,7 +153,13 @@ def isValid(cls, fieldDataType): class FieldMetaSpecial(object): """ - Public values for the "special" field attribute + Public values for the "special" field attribute. Valid values are: + + - ``R``: reset + - ``S``: sequence + - ``T``: timestamp + - ``C``: category + - ``L``: learning """ none = '' reset = 'R' @@ -149,9 +175,8 @@ class FieldMetaSpecial(object): def isValid(cls, attr): """Check a candidate value whether it's one of the valid attributes - :param str attr: candidate value + :param attr: (string) candidate value :returns: True if the candidate value is a legitimate "special" field - attribute; False if not - :rtype: bool + attribute; False if not """ return attr in cls._ALL