Merge pull request #1462 from zm711/core-docstrings

Switch Over Core Docstrings to New Style

Author: alejoe91

neo/core/dataobject.py

@@ -141,6 +141,20 @@ class DataObject(BaseNeo, pq.Quantity):
     This is the base class from which all objects containing data inherit
     It contains common functionality for all those objects and handles array_annotations.
 
+    Parameters
+    ----------
+    name: str | None, default: None
+        Name of the Neo object
+    description: str | None, default: None
+        Human readable string description of the Neo object
+    array_annotations: dict | None, default: None
+        Dictionary containing arrays / lists which annotate individual data points of the Neo object.
+    **annotations: dict | None:
+        Other keyword annotations to be included
+
+    Notes
+    -----
+
     Common functionality that is not included in BaseNeo includes:
     - duplicating with new data
     - rescaling the object
@@ -154,13 +168,6 @@ class DataObject(BaseNeo, pq.Quantity):
     They can contain the same data types as regular annotations, but are always represented
     as numpy arrays of the same length as the number of data points of the annotated neo object.
 
-    Args:
-        name (str, optional): Name of the Neo object
-        description (str, optional): Human readable string description of the Neo object
-        file_origin (str, optional): Origin of the data contained in this Neo object
-        array_annotations (dict, optional): Dictionary containing arrays / lists which annotate
-            individual data points of the Neo object.
-        kwargs: regular annotations stored in a separate annotation dictionary
     """
 
     def __init__(self, name=None, description=None, file_origin=None, array_annotations=None, **annotations):
@@ -182,8 +189,13 @@ def array_annotate(self, **array_annotations):
         Add array annotations (annotations for individual data points) as arrays to a Neo data
         object.
 
-        Example:
-
+        Parameters
+        ----------
+        **array_annotations: dict
+            Series of keyword annotations to add to the object
+        
+        Examples
+        --------
         >>> obj.array_annotate(code=['a', 'b', 'a'], category=[2, 1, 1])
         >>> obj.array_annotations['code'][1]
         'b'
@@ -194,12 +206,19 @@ def array_annotate(self, **array_annotations):
     def array_annotations_at_index(self, index):
         """
         Return dictionary of array annotations at a given index or list of indices
-        :param index: int, list, numpy array: The index (indices) from which the annotations
-                      are extracted
-        :return: dictionary of values or numpy arrays containing all array annotations
-                 for given index/indices
 
-        Example:
+        Parameters
+        ----------
+        index: int | list | np.ndarray
+            The index (indices) from which the annotations are extracted
+        
+        Returns
+        -------
+        index_annotations: dict
+            Dictionary of values or numpy arrays containing all array annotations for given index/indices
+
+        Examples
+        --------
         >>> obj.array_annotate(code=['a', 'b', 'a'], category=[2, 1, 1])
         >>> obj.array_annotations_at_index(1)
         {code='b', category=1}
@@ -228,10 +247,22 @@ def array_annotations_at_index(self, index):
     def _merge_array_annotations(self, other):
         """
         Merges array annotations of 2 different objects.
+
+        Parameters
+        ----------
+        other: any
+            The annotation to attemp to merge
+        
+        Returns
+        -------
+        merged_array_annotations: dict
+            The merged annotations
+        
+        Notes
+        -----
         The merge happens in such a way that the result fits the merged data
         In general this means concatenating the arrays from the 2 objects.
         If an annotation is only present in one of the objects, it will be omitted
-        :return Merged array_annotations
         """
 
         merged_array_annotations = {}
@@ -274,9 +305,23 @@ def _merge_array_annotations(self, other):
     def rescale(self, units, dtype=None):
         """
         Return a copy of the object converted to the specified units.
-        The `dtype` argument exists only for backward compatibility within quantities, see
+
+        Parameters
+        ----------
+        units: quantity unit
+            The units to convert the object to
+        dtype: a numpy dtype
+            Only exists for backward compatibility see [1]
+        
+        Returns
+        -------
+        self.copy(): Any
+            A copy of the object with the desired units
+        
+        Notes
+        -----
+        [1] The `dtype` argument exists only for backward compatibility within quantities, see
         https://github.com/python-quantities/python-quantities/pull/204
-        :return: Copy of self with specified units
         """
 
         # Use simpler functionality, if nothing will be changed
@@ -309,6 +354,16 @@ def as_array(self, units=None):
         """
         Return the object's data as a plain NumPy array.
 
+        Parameters
+        ----------
+        units: quantities units | None, default: None
+            The data return as a np.ndarray with units requested
+        
+        Returns
+        -------
+        data_array: np.ndarray
+            The data as an array
+
         If `units` is specified, first rescale to those units.
         """
         if units:
@@ -375,7 +430,7 @@ def __deepcopy__(self, memo):
         return new_obj
 
 
-class ArrayDict(dict):
+class ArrayDict(dict): 
     """Dictionary subclass to handle array annotations
 
     When setting `obj.array_annotations[key]=value`, checks for consistency

neo/core/epoch.py

@@ -51,6 +51,25 @@ class Epoch(DataObject):
     """
     Array of epochs.
 
+    Parameters
+    ----------
+    times: quantity array 1D | numpy array 1D | list | None, default: None
+        The start times of each time period.
+        If None, generates an empty array
+    durations: quantity array 1D | numpy array 1D | list |  quantity scalar | float | None, default: None
+        The length(s) of each time period.
+        If a scalar/float, the same value is used for all time periods.
+        If None, generates an empty array
+    labels: numpy.array 1D dtype='U' | list | None, default: None
+        Names or labels for the time periods.
+        If None, creates an empty array
+    units: quantity units | str | None, default: None
+        The units for the time
+        Required if the times is a list or NumPy, not required if it is a :class:`Quantity`
+    name: (str) A label for the dataset,
+    description: (str) Text description,
+    file_origin: (str) Filesystem path or URL of the original data file.
+
     *Usage*::
 
         >>> from neo.core import Epoch
@@ -69,20 +88,10 @@ class Epoch(DataObject):
         array(['btn0', 'btn1', 'btn2'],
               dtype='<U4')
 
-    *Required attributes/properties*:
-        :times: (quantity array 1D, numpy array 1D or list) The start times
-           of each time period.
-        :durations: (quantity array 1D, numpy array 1D, list, quantity scalar or float)
-           The length(s) of each time period.
-           If a scalar/float, the same value is used for all time periods.
-        :labels: (numpy.array 1D dtype='U' or list) Names or labels for the time periods.
-        :units: (quantity units or str) Required if the times is a list or NumPy
-                array, not if it is a :class:`Quantity`
+
 
     *Recommended attributes/properties*:
-        :name: (str) A label for the dataset,
-        :description: (str) Text description,
-        :file_origin: (str) Filesystem path or URL of the original data file.
+
 
     *Optional attributes/properties*:
         :array_annotations: (dict) Dict mapping strings to numpy arrays containing annotations \

neo/core/event.py

@@ -47,40 +47,46 @@ def _new_event(
 
 class Event(DataObject):
     """
-    Array of events.
-
-    *Usage*::
-
-        >>> from neo.core import Event
-        >>> from quantities import s
-        >>> import numpy as np
-        >>>
-        >>> evt = Event(np.arange(0, 30, 10)*s,
-        ...             labels=np.array(['trig0', 'trig1', 'trig2'],
-        ...                             dtype='U'))
-        >>>
-        >>> evt.times
-        array([  0.,  10.,  20.]) * s
-        >>> evt.labels
-        array(['trig0', 'trig1', 'trig2'],
+    Array of events which are the start times of events along with the labels
+    of the events
+
+    Parameters
+    ----------
+    times: quantity array 1d | list
+        The times of the events
+    labels: numpy.ndarray 1d dtype='U' | list
+        Names or labels for the events
+    units: quantity units | None, default: None
+        If times are list the units of the times
+        If times is a quantity array this is ignored
+    name: str | None, default: None
+        An optional label for the dataset
+    description: str | None, default: None
+        An optional text descriptoin of the dataset
+    file_orgin: str | None, default: None
+        The filesystem path or url of the original data file
+    array_annotations: dict | None, default: None
+        Dict mapping strings to numpy arrays containing annotations for all data points
+    **annotations: dict
+        Additional user specified metadata stored in the annotations attribue
+
+    Examples
+    --------
+
+    >>> from neo.core import Event
+    >>> from quantities import s
+    >>> import numpy as np
+    >>>
+    >>> evt = Event(np.arange(0, 30, 10)*s,
+    ...             labels=np.array(['trig0', 'trig1', 'trig2'],
+    ...                             dtype='U'))
+    >>>
+    >>> evt.times
+    array([  0.,  10.,  20.]) * s
+    >>> evt.labels
+    array(['trig0', 'trig1', 'trig2'],
               dtype='<U5')
 
-    *Required attributes/properties*:
-        :times: (quantity array 1D) The time of the events.
-        :labels: (numpy.array 1D dtype='U' or list) Names or labels for the events.
-
-    *Recommended attributes/properties*:
-        :name: (str) A label for the dataset.
-        :description: (str) Text description.
-        :file_origin: (str) Filesystem path or URL of the original data file.
-
-    *Optional attributes/properties*:
-        :array_annotations: (dict) Dict mapping strings to numpy arrays containing annotations \
-                                   for all data points
-
-    Note: Any other additional arguments are assumed to be user-specific
-    metadata and stored in :attr:`annotations`.
-
     """
 
     _parent_objects = ("Segment",)
@@ -212,9 +218,24 @@ def _repr_pretty_(self, pp, cycle):
     def rescale(self, units, dtype=None):
         """
         Return a copy of the :class:`Event` converted to the specified units
+
+        Parameters
+        ----------
+        units: quantity units
+            The units to convert the Event to
+        dtype: None
+            Exists for backward compatiblity within quantities see Notes for more info
+
+        Returns
+        -------
+        obj: neo.core.Event
+            A copy of the event with the specified units
+
+        Notes
+        -----
         The `dtype` argument exists only for backward compatibility within quantities, see
         https://github.com/python-quantities/python-quantities/pull/204
-        :return: Copy of self with specified units
+
         """
         # Use simpler functionality, if nothing will be changed
         dim = pq.quantity.validate_dimensionality(units)
@@ -235,12 +256,19 @@ def times(self):
 
     def merge(self, other):
         """
-        Merge the another :class:`Event` into this one.
-
-        The :class:`Event` objects are concatenated horizontally
+        Merge another :class:`Event` into this one.
+
+        Parameter
+        ---------
+        other: neo.core.Event
+            The `Event` to merge into this one
+        
+        Notes
+        -----
+        * The :class:`Event` objects are concatenated horizontally
         (column-wise), :func:`np.hstack`).
 
-        If the attributes of the two :class:`Event` are not
+        * If the attributes of the two :class:`Event` are not
         compatible, and Exception is raised.
         """
         othertimes = other.times.rescale(self.times.units)
@@ -319,10 +347,22 @@ def duplicate_with_new_data(self, times, labels, units=None):
 
     def time_slice(self, t_start, t_stop):
         """
-        Creates a new :class:`Event` corresponding to the time slice of
-        the original :class:`Event` between (and including) times
-        :attr:`t_start` and :attr:`t_stop`. Either parameter can also be None
-        to use infinite endpoints for the time interval.
+        Creates a new `Event` corresponding to the time slice of the original `Event` between (and including) times
+        `t_start` and `t_stop`.
+
+        Parameters
+        ----------
+        t_start: float | None
+            The starting time of the time slice
+            If None will use -np.inf for the starting time
+        t_stop: float | None
+            The stopping time of the time slice
+            If None will use np.inf for the stopping time
+
+        Returns
+        -------
+        new_evt: neo.core.Event
+            The new `Event` limited by the time points
         """
         _t_start = t_start
         _t_stop = t_stop