Skip to content

Time index

pynapple.core.time_index

Similar to pandas.Index, TsIndex holds the timestamps associated with the data of a time series. This class deals with conversion between different time units for all pynapple objects as well as making sure that timestamps are property sorted before initializing any objects.

- `us`: microseconds
- `ms`: milliseconds
- `s`: seconds  (overall default)

TsIndex

Bases: ndarray

Holder for timestamps. Similar to pandas.Index. Subclass numpy.ndarray

Source code in pynapple/core/time_index.py 
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
class TsIndex(np.ndarray):
    """
    Holder for timestamps. Similar to pandas.Index. Subclass numpy.ndarray
    """

    @staticmethod
    def format_timestamps(t, units="s"):
        """
        Converts time index in pynapple in a default format

        Parameters
        ----------
        t : numpy.ndarray
            a vector of times
        units
            the units in which times are given

        Returns
        -------
        t : np.ndarray
            times in standard pynapple format

        Raises
        ------
        ValueError
            Description
        """
        if units == "s":
            t = np.around(t, nap_config.time_index_precision)
        elif units == "ms":
            t = np.around(t / 1.0e3, nap_config.time_index_precision)
        elif units == "us":
            t = np.around(t / 1.0e6, nap_config.time_index_precision)
        else:
            raise ValueError("unrecognized time units type")

        return t

    @staticmethod
    def return_timestamps(t, units="s"):
        """
        Converts time index in pynapple in a particular format

        Parameters
        ----------
        t : numpy.ndarray
            a vector (or scalar) of times
        units
            the units in which times are given

        Returns
        -------
        t : numpy.ndarray
            times in standard pynapple format

        Raises
        ------
        ValueError
            IF units is not in ['s', 'ms', 'us']
        """
        if units == "s":
            t = np.around(t, nap_config.time_index_precision)
        elif units == "ms":
            t = np.around(t * 1.0e3, nap_config.time_index_precision)
        elif units == "us":
            t = np.around(t * 1.0e6, nap_config.time_index_precision)
        else:
            raise ValueError("unrecognized time units type")

        return t

    @staticmethod
    def sort_timestamps(t, give_warning=True):
        """
        Raise warning if timestamps are not sorted

        Parameters
        ----------
        t : numpy.ndarray
            a vector of times
        give_warning : bool, optional
            If timestamps are not sorted

        Returns
        -------
        numpy.ndarray
            Description
        """
        if not (np.diff(t) >= 0).all():
            if give_warning and not nap_config.suppress_time_index_sorting_warnings:
                warn("timestamps are not sorted", UserWarning)
            t = np.sort(t)
        return t

    def __new__(cls, t, time_units="s"):
        t = t.astype(np.float64).flatten()
        t = TsIndex.format_timestamps(t, time_units)
        t = TsIndex.sort_timestamps(t)
        obj = np.asarray(t).view(cls)
        return obj

    @property
    def values(self):
        """Returns the index as a ndarray

        Returns
        -------
        numpy.ndarray
            The timestamps in seconds
        """
        return np.asarray(self)

    def __setitem__(self, *args, **kwargs):
        raise RuntimeError("TsIndex object is not mutable.")

    def to_numpy(self):
        """Return the index as a ndarray. Useful for matplotlib.

        Returns
        -------
        numpy.ndarray
            The timestamps in seconds
        """
        return self.values

    def in_units(self, time_units="s"):
        """Return the index as a ndarray in the desired units

        Returns
        -------
        numpy.ndarray
            The timestamps in seconds
        """
        return TsIndex.return_timestamps(self.values, time_units)

values property 

values

Returns the index as a ndarray

Returns:

Type Description
ndarray

The timestamps in seconds

format_timestamps staticmethod 

format_timestamps(t, units='s')

Converts time index in pynapple in a default format

Parameters:

Name Type Description Default
t ndarray

a vector of times

 required
units

the units in which times are given

 's'

Returns:

Name Type Description
t ndarray

times in standard pynapple format

Raises:

Type Description
ValueError

Description
Source code in pynapple/core/time_index.py 
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
@staticmethod
def format_timestamps(t, units="s"):
    """
    Converts time index in pynapple in a default format

    Parameters
    ----------
    t : numpy.ndarray
        a vector of times
    units
        the units in which times are given

    Returns
    -------
    t : np.ndarray
        times in standard pynapple format

    Raises
    ------
    ValueError
        Description
    """
    if units == "s":
        t = np.around(t, nap_config.time_index_precision)
    elif units == "ms":
        t = np.around(t / 1.0e3, nap_config.time_index_precision)
    elif units == "us":
        t = np.around(t / 1.0e6, nap_config.time_index_precision)
    else:
        raise ValueError("unrecognized time units type")

    return t

return_timestamps staticmethod 

return_timestamps(t, units='s')

Converts time index in pynapple in a particular format

Parameters:

Name Type Description Default
t ndarray

a vector (or scalar) of times

 required
units

the units in which times are given

 's'

Returns:

Name Type Description
t ndarray

times in standard pynapple format

Raises:

Type Description
ValueError

IF units is not in ['s', 'ms', 'us']
Source code in pynapple/core/time_index.py 
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
@staticmethod
def return_timestamps(t, units="s"):
    """
    Converts time index in pynapple in a particular format

    Parameters
    ----------
    t : numpy.ndarray
        a vector (or scalar) of times
    units
        the units in which times are given

    Returns
    -------
    t : numpy.ndarray
        times in standard pynapple format

    Raises
    ------
    ValueError
        IF units is not in ['s', 'ms', 'us']
    """
    if units == "s":
        t = np.around(t, nap_config.time_index_precision)
    elif units == "ms":
        t = np.around(t * 1.0e3, nap_config.time_index_precision)
    elif units == "us":
        t = np.around(t * 1.0e6, nap_config.time_index_precision)
    else:
        raise ValueError("unrecognized time units type")

    return t

sort_timestamps staticmethod 

sort_timestamps(t, give_warning=True)

Raise warning if timestamps are not sorted

Parameters:

Name Type Description Default
t ndarray

a vector of times

 required
give_warning bool

If timestamps are not sorted

 True

Returns:

Type Description
ndarray

Description
Source code in pynapple/core/time_index.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
@staticmethod
def sort_timestamps(t, give_warning=True):
    """
    Raise warning if timestamps are not sorted

    Parameters
    ----------
    t : numpy.ndarray
        a vector of times
    give_warning : bool, optional
        If timestamps are not sorted

    Returns
    -------
    numpy.ndarray
        Description
    """
    if not (np.diff(t) >= 0).all():
        if give_warning and not nap_config.suppress_time_index_sorting_warnings:
            warn("timestamps are not sorted", UserWarning)
        t = np.sort(t)
    return t

to_numpy 

to_numpy()

Return the index as a ndarray. Useful for matplotlib.

Returns:

Type Description
ndarray

The timestamps in seconds
Source code in pynapple/core/time_index.py 
134
135
136
137
138
139
140
141
142
def to_numpy(self):
    """Return the index as a ndarray. Useful for matplotlib.

    Returns
    -------
    numpy.ndarray
        The timestamps in seconds
    """
    return self.values

in_units 

in_units(time_units='s')

Return the index as a ndarray in the desired units

Returns:

Type Description
ndarray

The timestamps in seconds
Source code in pynapple/core/time_index.py 
144
145
146
147
148
149
150
151
152
def in_units(self, time_units="s"):
    """Return the index as a ndarray in the desired units

    Returns
    -------
    numpy.ndarray
        The timestamps in seconds
    """
    return TsIndex.return_timestamps(self.values, time_units)