TsdFrame init examples

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

Hide file tree

Showing 2 changed files with 110 additions and 7 deletions.
diff --git a/pynapple/core/interval_set.py b/pynapple/core/interval_set.py
@@ -87,7 +87,7 @@ def __init__(
         metadata=None,
     ):
         """
-        `IntervalSet` object initializor.
+        IntervalSet initializer.
 
         If start and end are not aligned, meaning that:
         1. len(start) != len(end)
@@ -123,7 +123,7 @@ def __init__(
         >>> import pynapple as nap
         >>> import numpy as np
 
-        Initialize an `IntervalSet` object with a list of start and end times:
+        Initialize an IntervalSet with a list of start and end times:
 
         >>> start = [0, 10, 20]
         >>> end = [5, 12, 33]
@@ -135,7 +135,7 @@ def __init__(
               2       20     33
         shape: (3, 2), time unit: sec.
 
-        Initialize an `IntervalSet` object with an array of start and end pairs:
+        Initialize an IntervalSet with an array of start and end pairs:
 
         >>> times = np.array([[0, 5], [10, 12], [20, 33]])
         >>> ep = nap.IntervalSet(times)
@@ -146,7 +146,7 @@ def __init__(
               2       20     33
         shape: (3, 2), time unit: sec.
 
-        Initialize an `IntervalSet` object with metadata:
+        Initialize an IntervalSet with metadata:
 
         >>> start = [0, 10, 20]
         >>> end = [5, 12, 33]
@@ -158,7 +158,7 @@ def __init__(
               2       20     33  |   c
         shape: (3, 2), time unit: sec.
 
-        Initialize an `IntervalSet` object with a pandas DataFrame:
+        Initialize an IntervalSet with a pandas DataFrame:
 
         >>> import pandas as pd
         >>> df = pd.DataFrame(data={"start": [0, 10, 20], "end": [5, 12, 33], "label": ["a", "b", "c"]})

diff --git a/pynapple/core/time_series.py b/pynapple/core/time_series.py
@@ -900,7 +900,7 @@ def __init__(
         load_array=True,
         metadata=None,
     ):
-        """
+        r"""
         TsdFrame initializer
         A pandas.DataFrame can be passed directly
 
@@ -920,9 +920,112 @@ def __init__(
             Whether the data should be converted to a numpy (or jax) array. Useful when passing a memory map object like zarr.
             Default is True. Does not apply if `d` is already a numpy array.
         metadata: pd.DataFrame or dict, optional
-            Metadata associated with data columns
+            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
+        --------
+        Initialize a TsdFrame:
+
+        >>> import pynapple as nap
+        >>> import numpy as np
+        >>> t = np.arange(100)
+        >>> d = np.ones((100, 3))
+        >>> tsdframe = nap.TsdFrame(t=t, d=d)
+        >>> tsdframe
+        Time (s)    0    1    2
+        ----------  ---  ---  ---
+        0.0         1.0  1.0  1.0
+        1.0         1.0  1.0  1.0
+        2.0         1.0  1.0  1.0
+        3.0         1.0  1.0  1.0
+        4.0         1.0  1.0  1.0
+        ...         ...  ...  ...
+        95.0        1.0  1.0  1.0
+        96.0        1.0  1.0  1.0
+        97.0        1.0  1.0  1.0
+        98.0        1.0  1.0  1.0
+        99.0        1.0  1.0  1.0
+        dtype: float64, shape: (100, 3)
+
+        Initialize a TsdFrame with column names:
+
+        >>> tsdframe = nap.TsdFrame(t=t, d=d, columns=['A', 'B', 'C'])
+        >>> tsdframe
+        Time (s)    A    B    C
+        ----------  ---  ---  ---
+        0.0         1.0  1.0  1.0
+        1.0         1.0  1.0  1.0
+        2.0         1.0  1.0  1.0
+        3.0         1.0  1.0  1.0
+        4.0         1.0  1.0  1.0
+        ...         ...  ...  ...
+        95.0        1.0  1.0  1.0
+        96.0        1.0  1.0  1.0
+        97.0        1.0  1.0  1.0
+        98.0        1.0  1.0  1.0
+        99.0        1.0  1.0  1.0
+        dtype: float64, shape: (100, 3)
+
+        Initialize a TsdFrame with metadata:
+
+        >>> metadata = {"color": ["red", "blue", "green"], "depth": [1, 2, 3]}
+        >>> tsdframe = nap.TsdFrame(t=t, d=d, columns=["A", "B", "C"], metadata=metadata)
+        >>> tsdframe
+        Time (s)    A         B         C
+        ----------  --------  --------  --------
+        0.0         1.0       1.0       1.0
+        1.0         1.0       1.0       1.0
+        2.0         1.0       1.0       1.0
+        3.0         1.0       1.0       1.0
+        4.0         1.0       1.0       1.0
+        ...         ...       ...       ...
+        95.0        1.0       1.0       1.0
+        96.0        1.0       1.0       1.0
+        97.0        1.0       1.0       1.0
+        98.0        1.0       1.0       1.0
+        99.0        1.0       1.0       1.0
+        Metadata
+        --------    --------  --------  --------
+        color       red       blue      green
+        depth       1         2         3
+        <BLANKLINE>
+        dtype: float64, shape: (100, 3)
+
+        Initialize a TsdFrame with a pandas DataFrame:
+
+        >>> import pandas as pd
+        >>> data = pd.DataFrame(index=t, columns=["A", "B", "C"], data=d)
+        >>> metadata = pd.DataFrame(
+        ...    index=["A", "B", "C"],
+        ...    columns=["color", "depth"],
+        ...    data=[["red", 1], ["blue", 2], ["green", 3]],
+        ... )
+        >>> tsdframe = nap.TsdFrame(data, metadata=metadata)
+        >>> tsdframe
+        Time (s)    A         B         C
+        ----------  --------  --------  --------
+        0.0         1.0       1.0       1.0
+        1.0         1.0       1.0       1.0
+        2.0         1.0       1.0       1.0
+        3.0         1.0       1.0       1.0
+        4.0         1.0       1.0       1.0
+        ...         ...       ...       ...
+        95.0        1.0       1.0       1.0
+        96.0        1.0       1.0       1.0
+        97.0        1.0       1.0       1.0
+        98.0        1.0       1.0       1.0
+        99.0        1.0       1.0       1.0
+        Metadata
+        --------    --------  --------  --------
+        color       red       blue      green
+        depth       1         2         3
+        <BLANKLINE>
+        dtype: float64, shape: (100, 3)
+
         """
 
         c = columns