Merge pull request #1397 from zm711/docstrings

Add and unify many docstrings

Author: apdavison

neo/io/basefromrawio.py

@@ -4,12 +4,12 @@
 
 BaseFromRaw implement a bridge between the new neo.rawio API
 and the neo.io legacy that give neo.core object.
-The neo.rawio API is more restricted and limited and do not cover tricky
+The neo.rawio API is more restricted and limited and does not cover tricky
 cases with asymetrical tree of neo object.
 But if a format is done in neo.rawio the neo.io is done for free
 by inheritance of this class.
-Furthermore, IOs that inherits this BaseFromRaw also have the ability
-of the lazy load with proxy objects.
+Furthermore, IOs that inherit this BaseFromRaw also have the ability
+to lazy load with proxy objects.
 
 
 """
@@ -80,26 +80,34 @@ def read_block(
         self, block_index=0, lazy=False, create_group_across_segment=None, signal_group_mode=None, load_waveforms=False
     ):
         """
-        :param block_index: int default 0. In case of several block block_index can be specified.
-
-        :param lazy: False by default.
-
-        :param create_group_across_segment: bool or dict
+        Reads one block of data from a file
+
+        Parameters
+        ----------
+        block_index: int, default: 0
+            In the case of multiple blocks, the block_index specifies which block to read
+        lazy: bool, default: False
+            Whether to read the block lazily (True) or load into memory (False)
+        create_group_across_segment: bool | dict | None, default: None
             If True :
-              * Create a neo.Group to group AnalogSignal segments
-              * Create a neo.Group to group SpikeTrain across segments
-              * Create a neo.Group to group Event across segments
-              * Create a neo.Group to group Epoch across segments
+                * Create a neo.Group to group AnalogSignal segments
+                * Create a neo.Group to group SpikeTrain across segments
+                * Create a neo.Group to group Event across segments
+                * Create a neo.Group to group Epoch across segments
             With a dict the behavior can be controlled more finely
-            create_group_across_segment = { 'AnalogSignal': True, 'SpikeTrain': False, ...}
-
-        :param signal_group_mode: 'split-all' or 'group-by-same-units' (default depend IO):
-        This control behavior for grouping channels in AnalogSignal.
-            * 'split-all': each channel will give an AnalogSignal
-            * 'group-by-same-units' all channel sharing the same quantity units ar grouped in
-            a 2D AnalogSignal
-
-        :param load_waveforms: False by default. Control SpikeTrains.waveforms is None or not.
+                * for example: create_group_across_segment = { 'AnalogSignal': True, 'SpikeTrain': False, ...}
+        signal_group_mode: 'split-all' | 'group-by-same-units' | None, default: None
+            This control behavior for grouping channels in AnalogSignal.
+                * 'split-all': each channel will be give an AnalogSignal
+                * 'group-by-same-units' all channel sharing the same quantity units are grouped in a 2D AnalogSignal
+            By default None since the default is dependant on the IO
+        load_waveforms: bool, default: False
+            Determines whether SpikeTrains.waveforms is created
+        
+        Returns
+        -------
+        bl: neo.core.Block
+            The block of data
 
         """
 
@@ -200,31 +208,40 @@ def read_segment(
         strict_slicing=True,
     ):
         """
-        :param block_index: int default 0. In case of several blocks block_index can be specified.
-
-        :param seg_index: int default 0. Index of segment.
-
-        :param lazy: False by default.
-
-        :param signal_group_mode: 'split-all' or 'group-by-same-units' (default depend IO):
-        This control behavior for grouping channels in AnalogSignal.
-            * 'split-all': each channel will give an AnalogSignal
-            * 'group-by-same-units' all channel sharing the same quantity units ar grouped in
-            a 2D AnalogSignal
-
-        :param load_waveforms: False by default. Control SpikeTrains.waveforms is None or not.
-
-        :param time_slice: None by default means no limit.
-            A time slice is (t_start, t_stop) both are quantities.
-            All object AnalogSignal, SpikeTrain, Event, Epoch will load only in the slice.
-
-        :param strict_slicing: True by default.
-             Control if an error is raised or not when t_start or t_stop
-             is outside the real time range of the segment.
+        Reads one segment of the data file
+
+        Parameters
+        ----------
+        block_index: int, default: 0
+            In the case of a multiblock dataset, this specifies which block to read
+        seg_index: int, default: 0
+            In the case of a multisegment block, this specifies which segmeent to read
+        lazy: bool, default: False
+            Whether to lazily load the segment (True) or to load the segment into memory (False)
+        signal_group_mode: 'split-all' | 'group-by-same-units' | None, default: None
+           This control behavior for grouping channels in AnalogSignal.
+            * 'split-all': each channel will be give an AnalogSignal
+            * 'group-by-same-units' all channel sharing the same quantity units are grouped in a 2D AnalogSignal
+        load_waveforms: bool, default: False
+            Determines whether SpikeTrains.waveforms is created
+        time_slice: tuple[quantity.Quantities | None] | None, default: None
+            Whether to take a time slice of the data
+                * None: indicates from beginning of the segment to the end of the segment
+                * tuple: (t_start, t_stop) with t_start and t_stop being quantities in seconds
+                * tuple: (None, t_stop) indicates the beginning of the segment to t_stop
+                * tuple: (t_start, None) indicates from t_start to the end of the segment
+        strict_slicing: bool, default: True
+            Control if an error is raised or not when t_start or t_stop
+            is outside of the real time range of the segment.
+
+        Returns
+        -------
+        seg: neo.core.Segment
+            Returns the desired segment based on the parameters given
         """
 
         if lazy:
-            assert time_slice is None, "For lazy=True you must specify time_slice when LazyObject.load(time_slice=...)"
+            assert time_slice is None, "For lazy=True you must specify a time_slice when LazyObject.load(time_slice=...)"
 
             assert (
                 not load_waveforms
@@ -317,7 +334,7 @@ def get_sub_signal_streams(self, signal_group_mode="group-by-same-units"):
 
                 if len(all_units) == 1:
                     # no substream
-                    #  None iwill be transform as slice later
+                    # None iwill be transform as slice later
                     inner_stream_channels = None
                     name = stream_name
                     sub_stream = (stream_index, inner_stream_channels, name)

neo/io/baseio.py

@@ -125,6 +125,18 @@ def __init__(self, filename: str | Path = None, **kargs):
     def read(self, lazy: bool = False, **kargs):
         """
         Return all data from the file as a list of Blocks
+
+        Parameters
+        ----------
+        lazy: bool, default: False
+            Whether to lazily load the data (True) or to load into memory (False)
+        kargs: dict
+            IO specific additional arguments
+        
+        Returns
+        ------
+        block_list: list[neo.core.Block]
+            Returns all the data from the file as Blocks
         """
         if lazy and not self.support_lazy:
             raise ValueError("This IO module does not support lazy loading")
@@ -142,6 +154,17 @@ def read(self, lazy: bool = False, **kargs):
             raise NotImplementedError
 
     def write(self, bl, **kargs):
+        """
+        Writes a given block if IO supports writing
+
+        Parameters
+        ----------
+        bl: neo.core.Block
+            The neo Block to be written
+        kargs: dict
+            IO specific additional arguments
+            
+        """
         if Block in self.writeable_objects:
             if isinstance(bl, Sequence):
                 assert hasattr(self, "write_all_blocks"), (

neo/rawio/alphaomegarawio.py

@@ -47,20 +47,21 @@
 class AlphaOmegaRawIO(BaseRawIO):
     """
     AlphaOmega MPX file format 4 reader. Handles several segments.
-
-    A segment is a continuous record (when record starts/stops).
-
+    A segment is a continuous recording (when recording starts/stops).
     Only files in current `dirname` are loaded, subfolders are not explored.
 
-    :param dirname: folder from where to load the data
-    :type dirname: str or Path-like
-    :param lsx_files: list of lsx files in `dirname` referencing mpx files to
-        load (optional). If None (default), read all mpx files in `dirname`
-    :type lsx_files: list of strings or None
-    :param prune_channels: if True removes the empty channels, defaults to True
-    :type prune_channels: bool
-
-    .. warning::
+    Parameters
+    ----------
+    dirname: str | Path
+        The folder from which the data will be loaded
+    lsx_files: list[str] | None, default: None
+        List of lsx files in `dirname` referencing mpx files to load (optional)
+        If None all mpx files will be read
+    prune_channels: bool, default: True
+        If True removes the empty channels
+
+    Notes
+    -----
         Because channels must be gathered into coherent streams, channels names
         **must** be the default channel names in AlphaRS or Alpha LAB SNR
         software.

neo/rawio/axographrawio.py

@@ -174,52 +174,50 @@ class AxographRawIO(BaseRawIO):
     """
     RawIO class for reading AxoGraph files (.axgd, .axgx)
 
-    Args:
-        filename (string):
-            File name of the AxoGraph file to read.
-        force_single_segment (bool):
-            Episodic files are normally read as multi-Segment Neo objects. This
-            parameter can force AxographRawIO to put all signals into a single
-            Segment. Default: False.
-
-    Example:
+    Parameters
+    ----------
+    filename: str
+        File name of the AxoGraph file to read.
+    force_single_segment: bool, default: False
+        Episodic files are normally read as multi-Segment Neo objects. This
+        parameter can force AxographRawIO to put all signals into a single
+        Segment.
+
+    Examples
+    --------
         >>> import neo
-        >>> r = neo.rawio.AxographRawIO(filename=filename)
-        >>> r.parse_header()
-        >>> print(r)
+        >>> reader = neo.rawio.AxographRawIO(filename=filename)
+        >>> reader.parse_header()
+        >>> print(reader)
 
         >>> # get signals
-        >>> raw_chunk = r.get_analogsignal_chunk(
-        ...     block_index=0, seg_index=0,
-        ...     i_start=0, i_stop=1024,
-        ...     channel_names=channel_names)
-        >>> float_chunk = r.rescale_signal_raw_to_float(
-        ...     raw_chunk,
-        ...     dtype='float64',
-        ...     channel_names=channel_names)
+        >>> raw_chunk = reader.get_analogsignal_chunk(block_index=0,
+        ...                                           seg_index=0,
+        ...                                           i_start=0,
+        ...                                           i_stop=1024,
+        ...                                           channel_names=channel_names)
+        
+        >>> float_chunk = r.rescale_signal_raw_to_float(raw_chunk,
+        ...                                             dtype='float64',
+        ...                                             channel_names=channel_names)  
         >>> print(float_chunk)
 
         >>> # get event markers
-        >>> ev_raw_times, _, ev_labels = r.get_event_timestamps(
-        ...     event_channel_index=0)
-        >>> ev_times = r.rescale_event_timestamp(
-        ...     ev_raw_times, dtype='float64')
+        >>> ev_raw_times, _, ev_labels = reader.get_event_timestamps(event_channel_index=0)
+        >>> ev_times = reader.rescale_event_timestamp(ev_raw_times, dtype='float64')
         >>> print([ev for ev in zip(ev_times, ev_labels)])
 
         >>> # get interval bars
-        >>> ep_raw_times, ep_raw_durations, ep_labels = r.get_event_timestamps(
-        ...     event_channel_index=1)
-        >>> ep_times = r.rescale_event_timestamp(
-        ...     ep_raw_times, dtype='float64')
-        >>> ep_durations = r.rescale_epoch_duration(
-        ...     ep_raw_durations, dtype='float64')
+        >>> ep_raw_times, ep_raw_durations, ep_labels = reader.get_event_timestamps(event_channel_index=1)
+        >>> ep_times = reader.rescale_event_timestamp(ep_raw_times, dtype='float64')
+        >>> ep_durations = reader.rescale_epoch_duration(ep_raw_durations, dtype='float64') 
         >>> print([ep for ep in zip(ep_times, ep_durations, ep_labels)])
 
         >>> # get notes
-        >>> print(r.info['notes'])
+        >>> print(reader.info['notes'])
 
         >>> # get other miscellaneous info
-        >>> print(r.info)
+        >>> print(reader.info)
     """
 
     name = "AxographRawIO"

neo/rawio/axonarawio.py

@@ -32,25 +32,36 @@
 
 class AxonaRawIO(BaseRawIO):
     """
-    Class for reading raw, continuous data from the Axona dacqUSB system:
+    Class for reading raw, continuous data from the Axona dacqUSB system
+
+    Parameters
+    ----------
+    filename: str
+        The name of the *.bin file containing the data
+
+    Notes
+    -----
+
     http://space-memory-navigation.org/DacqUSBFileFormats.pdf
 
     The raw data is saved in .bin binary files with an accompanying .set
     file about the recording setup (see the above manual for details).
 
-    Usage::
-
-        import neo.rawio
-        r = neo.rawio.AxonaRawIO(filename=os.path.join(dir_name, base_filename))
-        r.parse_header()
-        print(r)
-        raw_chunk = r.get_analogsignal_chunk(block_index=0, seg_index=0,
-                                             i_start=0, i_stop=1024,
-                                             channel_names=channel_names)
-        float_chunk = reader.rescale_signal_raw_to_float(
-            raw_chunk, dtype='float64',
-            channel_indexes=[0, 3, 6]
-        )
+    Examples
+    --------
+
+        >>> import neo.rawio
+        >>> r = neo.rawio.AxonaRawIO(filename=os.path.join(dir_name, base_filename))
+        >>> r.parse_header()
+        >>> print(r)
+        >>> raw_chunk = r.get_analogsignal_chunk(block_index=0,
+                                                 seg_index=0,
+                                                 i_start=0,
+                                                 i_stop=1024,
+                                                 channel_names=channel_names)
+        >>> float_chunk = reader.rescale_signal_raw_to_float(raw_chunk,
+                                                             dtype='float64',
+                                                             channel_indexes=[0, 3, 6])
 
     """
 

neo/rawio/axonrawio.py

@@ -53,6 +53,29 @@
 
 
 class AxonRawIO(BaseRawIO):
+    """
+    Class for Class for reading data from pCLAMP and AxoScope files (.abf version 1 and 2)
+    
+    Parameters
+    ----------
+    filename: str, default: ''
+        The *.abf file to be read
+    
+    Notes
+    -----
+    This code is a port of abfload and abf2load written in Matlab (BSD-2-Clause licence) by
+    Copyright (c) 2009, Forrest Collman, [email protected]
+    Copyright (c) 2004, Harald Hentschke
+
+    Examples
+    --------
+
+    >>> import neo.rawio
+    >>> reader = neo.rawio.AxonRawIO(filename='mydata.abf')
+    >>> reader.parse_header()
+    >>> print(reader)
+
+    """
     extensions = ["abf"]
     rawmode = "one-file"