docstring examples for tsgroup init

pynapple-org · Nov 15, 2024 · 293a9d6 · 293a9d6
1 parent cef458d
commit 293a9d6
Show file tree

Hide file tree

Showing 2 changed files with 87 additions and 4 deletions.
diff --git a/pynapple/core/time_series.py b/pynapple/core/time_series.py
@@ -923,8 +923,6 @@ def __init__(
             Metadata associated with data columns. Metadata names are pulled from DataFrame columns or dictionary keys.
             The length of the metadata should match the number of data columns.
             If a DataFrame is passed, the index should match the columns of the TsdFrame.
-        **kwargs : dict, optional
-            Additional keyword arguments for labelling with metadata columns of the TsdFrame. The metadata should be the same length as the number of columns of the TsdFrame.
 
         Examples
         --------

diff --git a/pynapple/core/ts_group.py b/pynapple/core/ts_group.py
@@ -100,10 +100,12 @@ def __init__(
             To avoid checking that each element is within time_support.
             Useful to speed up initialization of TsGroup when Ts/Tsd objects have already been restricted beforehand
         metadata: pd.DataFrame or dict, optional
-            Metadata associated with each Ts/Tsd object
+            Metadata associated with each Ts/Tsd object. Metadata names are pulled from DataFrame columns or dictionary keys.
+            The length of the metadata should match the number of Ts/Tsd objects.
         **kwargs
             Meta-info about the Ts/Tsd objects. Can be either pandas.Series, numpy.ndarray, list or tuple
-            Note that the index should match the index of the input dictionary if pandas Series
+            The index should match the index of the input dictionary if pandas Series.
+            NOTE: This method of initializing metadata is deprecated and will be removed in a future version of Pynapple.
 
         Raises
         ------
@@ -114,6 +116,89 @@ def __init__(
             - If a key was a floating point with non-negligible decimal part.
             - If the converted keys are not unique, i.e. {1: ts_2, "2": ts_2} is valid,
             {1: ts_2, "1": ts_2}  is invalid.
+
+        Examples
+        --------
+        Initialize a TsGroup as a dictionary of Ts/Tsd objects:
+
+        >>> import pynapple as nap
+        >>> import numpy as np
+        >>> data = {
+        ...    0: nap.Ts(np.arange(100)),
+        ...    1: nap.Ts(np.arange(0, 100, 2)),
+        ...    2: nap.Ts(np.arange(0, 100, 3)),
+        ... }
+        >>> tsgroup = nap.TsGroup(data)
+        >>> tsgroup
+          Index     rate
+        -------  -------
+              0  1.0101
+              1  0.50505
+              2  0.34343
+
+        Initialize a TsGroup as a list of Ts/Tsd objects:
+
+        >>> data = [
+        ...    nap.Ts(np.arange(100)),
+        ...    nap.Ts(np.arange(0, 100, 2)),
+        ...    nap.Ts(np.arange(0, 100, 3)),
+        ... ]
+        >>> tsgroup = nap.TsGroup(data)
+        >>> tsgroup
+          Index     rate
+        -------  -------
+              0  1.0101
+              1  0.50505
+              2  0.34343
+
+        Initialize a TsGroup as a list of array (throws UserWarning):
+
+        >>> data = [
+        ...    np.arange(100),
+        ...    np.arange(0, 100, 2),
+        ...    np.arange(0, 100, 3),
+        ... ]
+        >>> tsgroup = nap.TsGroup(data)
+        >>> tsgroup
+          Index     rate
+        -------  -------
+              0  1.0101
+              1  0.50505
+              2  0.34343
+
+        Initialize a TsGroup with metadata:
+
+        >>> data = {
+        ...    0: nap.Ts(np.arange(100)),
+        ...    1: nap.Ts(np.arange(0, 100, 2)),
+        ...    2: nap.Ts(np.arange(0, 100, 3)),
+        ... }
+        >>> metadata = {"label": ["A", "B", "C"]}
+        >>> tsgroup = nap.TsGroup(data, metadata=metadata)
+        >>> tsgroup
+          Index     rate  label
+        -------  -------  -------
+              0  1.0101   A
+              1  0.50505  B
+              2  0.34343  C
+
+        Initialize a TsGroup with metadata as a pandas DataFrame:
+
+        >>> data = {
+        ...    0: nap.Ts(np.arange(100)),
+        ...    1: nap.Ts(np.arange(0, 100, 2)),
+        ...    2: nap.Ts(np.arange(0, 100, 3)),
+        ... }
+        >>> metadata = pd.DataFrame(data=["A", "B", "C"], columns=["label"])
+        >>> tsgroup = nap.TsGroup(data, metadata=metadata)
+        >>> tsgroup
+          Index     rate  label
+        -------  -------  -------
+              0  1.0101   A
+              1  0.50505  B
+              2  0.34343  C
+
+
         """
         # Check input type
         if time_units not in ["s", "ms", "us"]: