Merge pull request #1143 from TomDonoghue/docmn

[DOC] - Maintenance of in-code comments and docstrings

Author: JuliaSprenger

neo/core/analogsignal.py

@@ -2,7 +2,7 @@
 This module implements :class:`AnalogSignal`, an array of analog signals.
 
 :class:`AnalogSignal` inherits from :class:`basesignal.BaseSignal` which
-derives from :class:`BaseNeo`, and from :class:`quantites.Quantity`which
+derives from :class:`BaseNeo`, and from :class:`quantities.Quantity`which
 in turn inherits from :class:`numpy.array`.
 
 Inheritance from :class:`numpy.array` is explained here:
@@ -481,13 +481,13 @@ def time_shift(self, t_shift):
         """
         Shifts a :class:`AnalogSignal` to start at a new time.
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
         t_shift: Quantity (time)
             Amount of time by which to shift the :class:`AnalogSignal`.
 
-        Returns:
-        --------
+        Returns
+        -------
         new_sig: :class:`AnalogSignal`
             New instance of a :class:`AnalogSignal` object starting at t_shift later than the
             original :class:`AnalogSignal` (the original :class:`AnalogSignal` is not modified).
@@ -538,19 +538,19 @@ def downsample(self, downsampling_factor, **kwargs):
         arguments, except for specifying the axis of resampling, which is fixed to the first axis
         here.
 
-        Parameters:
-        -----------
-        downsampling_factor: integer
+        Parameters
+        ----------
+        downsampling_factor: int
             Factor used for decimation of samples. Scipy recommends to call decimate multiple times
             for downsampling factors higher than 13 when using IIR downsampling (default).
 
-        Returns:
-        --------
+        Returns
+        -------
         downsampled_signal: :class:`AnalogSignal`
             New instance of a :class:`AnalogSignal` object containing the resampled data points.
             The original :class:`AnalogSignal` is not modified.
 
-        Note:
+        Notes
         -----
         For resampling the signal with a fixed number of samples, see `resample` method.
         """
@@ -581,19 +581,19 @@ def resample(self, sample_count, **kwargs):
         arguments, except for specifying the axis of resampling which is fixed to the first axis
         here, and the sample positions. .
 
-        Parameters:
-        -----------
-        sample_count: integer
+        Parameters
+        ----------
+        sample_count: int
             Number of desired samples. The resulting signal starts at the same sample as the
             original and is sampled regularly.
 
-        Returns:
-        --------
+        Returns
+        -------
         resampled_signal: :class:`AnalogSignal`
             New instance of a :class:`AnalogSignal` object containing the resampled data points.
             The original :class:`AnalogSignal` is not modified.
 
-        Note:
+        Notes
         -----
         For reducing the number of samples to a fraction of the original, see `downsample` method
         """
@@ -625,8 +625,8 @@ def rectify(self, **kwargs):
         This method is a wrapper of numpy.absolute() and accepts the same set of keyword
         arguments.
 
-        Returns:
-        --------
+        Returns
+        -------
         resampled_signal: :class:`AnalogSignal`
             New instance of a :class:`AnalogSignal` object containing the rectified data points.
             The original :class:`AnalogSignal` is not modified.

neo/core/basesignal.py

@@ -311,4 +311,4 @@ def concatenate(self, *signals):
             If `other` object has incompatible attributes.
         '''
 
-        NotImplementedError('Patching need to be implemented in sublcasses')
+        NotImplementedError('Patching need to be implemented in subclasses')

neo/core/block.py

@@ -1,6 +1,6 @@
 '''
 This module defines :class:`Block`, the main container gathering all the data,
-whether discrete or continous, for a given recording session. base class
+whether discrete or continuous, for a given recording session. base class
 used by all :module:`neo.core` classes.
 
 :class:`Block` derives from :class:`Container`,
@@ -14,7 +14,7 @@
 
 class Block(Container):
     '''
-    Main container gathering all the data, whether discrete or continous, for a
+    Main container gathering all the data, whether discrete or continuous, for a
     given recording session.
 
     A block is not necessarily temporally homogeneous, in contrast to :class:`Segment`.
@@ -78,7 +78,7 @@ def __init__(self, name=None, description=None, file_origin=None,
                  file_datetime=None, rec_datetime=None, index=None,
                  **annotations):
         '''
-        Initalize a new :class:`Block` instance.
+        Initialize a new :class:`Block` instance.
         '''
         super().__init__(name=name, description=description,
                                     file_origin=file_origin, **annotations)

neo/core/container.py

@@ -228,7 +228,7 @@ class Container(BaseNeo):
     def __init__(self, name=None, description=None, file_origin=None,
                  **annotations):
         """
-        Initalize a new :class:`Container` instance.
+        Initialize a new :class:`Container` instance.
         """
         super().__init__(name=name, description=description,
                          file_origin=file_origin, **annotations)
@@ -466,7 +466,7 @@ def create_many_to_one_relationship(self, force=False, recursive=True):
         that this method will link up.
 
         If force is True overwrite any existing relationships
-        If recursive is True desecend into child objects and create
+        If recursive is True descend into child objects and create
         relationships there
         """
         parent_name = _reference_name(self.__class__.__name__)
@@ -485,7 +485,7 @@ def create_many_to_many_relationship(self, append=True, recursive=True):
         of this type, put the current object in the parent list.
 
         If append is True add it to the list, otherwise overwrite the list.
-        If recursive is True desecend into child objects and create
+        If recursive is True descend into child objects and create
         relationships there
         """
         parent_name = _container_name(self.__class__.__name__)
@@ -517,7 +517,7 @@ def create_relationship(self, force=False, append=True, recursive=True):
 
         If force is True overwrite any existing relationships
         If append is True add it to the list, otherwise overwrite the list.
-        If recursive is True desecend into child objects and create
+        If recursive is True descend into child objects and create
         relationships there
         """
         self.create_many_to_one_relationship(force=force, recursive=False)

neo/core/dataobject.py

@@ -18,16 +18,22 @@ def _normalize_array_annotations(value, length):
     Recursively check that value is either an array or list containing only "simple" types
     (number, string, date/time) or is a dict of those.
 
-    Args:
-        :value: (np.ndarray, list or dict) value to be checked for consistency
-        :length: (int) required length of the array annotation
-
-    Returns:
-        np.ndarray The array_annotations from value in correct form
-
-    Raises:
-        ValueError: In case value is not accepted as array_annotation(s)
-
+    Parameters
+    ----------
+    value : np.ndarray or list or dict
+        Value to be checked for consistency.
+    length : int
+        Required length of the array annotation.
+
+    Returns
+    -------
+    np.ndarray
+        The array_annotations from value in correct form
+
+    Raises
+    ------
+    ValueError
+        In case value is not accepted as array_annotation(s)
     """
 
     # First stage, resolve dict of annotations into single annotations
@@ -124,7 +130,7 @@ def _check_single_elem(element):
 
             # Check the first element for correctness
             # If its type is correct for annotations, all others are correct as well
-            # Note: Emtpy lists cannot reach this point
+            # Note: Empty lists cannot reach this point
             _check_single_elem(value[0])
 
     return value

neo/core/epoch.py

@@ -318,13 +318,13 @@ def time_shift(self, t_shift):
         """
         Shifts an :class:`Epoch` by an amount of time.
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
         t_shift: Quantity (time)
             Amount of time by which to shift the :class:`Epoch`.
 
-        Returns:
-        --------
+        Returns
+        -------
         epoch: :class:`Epoch`
             New instance of an :class:`Epoch` object starting at t_shift later than the
             original :class:`Epoch` (the original :class:`Epoch` is not modified).

neo/core/event.py

@@ -287,13 +287,13 @@ def time_shift(self, t_shift):
         """
         Shifts an :class:`Event` by an amount of time.
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
         t_shift: Quantity (time)
             Amount of time by which to shift the :class:`Event`.
 
-        Returns:
-        --------
+        Returns
+        -------
         epoch: Event
             New instance of an :class:`Event` object starting at t_shift later than the
             original :class:`Event` (the original :class:`Event` is not modified).

neo/core/imagesequence.py

@@ -2,7 +2,7 @@
 This module implements :class:`ImageSequence`, a 3D array.
 
 :class:`ImageSequence` inherits from :class:`basesignal.BaseSignal` which
-derives from :class:`BaseNeo`, and from :class:`quantites.Quantity`which
+derives from :class:`BaseNeo`, and from :class:`quantities.Quantity`which
 in turn inherits from :class:`numpy.array`.
 
 Inheritance from :class:`numpy.array` is explained here:

neo/core/irregularlysampledsignal.py

@@ -356,14 +356,14 @@ def resample(self, sample_count, **kwargs):
         arguments, except for specifying the axis of resampling which is fixed to the first axis
         here, and the sample positions. .
 
-        Parameters:
-        -----------
-        sample_count: integer
+        Parameters
+        ----------
+        sample_count: int
             Number of desired samples. The resulting signal starts at the same sample as the
             original and is sampled regularly.
 
-        Returns:
-        --------
+        Returns
+        -------
         resampled_signal: :class:`AnalogSignal`
             New instance of a :class:`AnalogSignal` object containing the resampled data points.
             The original :class:`AnalogSignal` is not modified.
@@ -431,13 +431,13 @@ def time_shift(self, t_shift):
         """
         Shifts a :class:`IrregularlySampledSignal` to start at a new time.
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
         t_shift: Quantity (time)
             Amount of time by which to shift the :class:`IrregularlySampledSignal`.
 
-        Returns:
-        --------
+        Returns
+        -------
         new_sig: :class:`SpikeTrain`
             New instance of a :class:`IrregularlySampledSignal` object
             starting at t_shift later than the original :class:`IrregularlySampledSignal`

neo/core/segment.py

@@ -20,7 +20,7 @@ class Segment(Container):
     '''
     A container for data sharing a common time basis.
 
-    A :class:`Segment` is a heterogeneous container for discrete or continous
+    A :class:`Segment` is a heterogeneous container for discrete or continuous
     data sharing a common clock (time basis) but not necessary the same
     sampling rate, start or end time.
 
@@ -145,25 +145,22 @@ def time_slice(self, t_start=None, t_stop=None, reset_time=False, **kwargs):
         Creates a time slice of a Segment containing slices of all child
         objects.
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
         t_start: Quantity
             Starting time of the sliced time window.
         t_stop: Quantity
             Stop time of the sliced time window.
-        reset_time: bool
+        reset_time: bool, optional, default: False
             If True the time stamps of all sliced objects are set to fall
             in the range from t_start to t_stop.
             If False, original time stamps are retained.
-            Default is False.
-
-        Keyword Arguments:
-        ------------------
+        **kwargs
             Additional keyword arguments used for initialization of the sliced
             Segment object.
 
-        Returns:
-        --------
+        Returns
+        -------
         subseg: Segment
             Temporal slice of the original Segment from t_start to t_stop.
         """