timelined_array 0.0.4__tar.gz → 0.0.6__tar.gz

timelined_array-0.0.6/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.1
+Name: timelined_array
+Version: 0.0.6
+Summary: Manage easily 1 or multidimensionnal samples numpy arrays that are time related. Extends numpy without removing any of it's abilities on such arrays.
+Author-Email: Timothe Jost <timothe.jost@wanadoo.fr>
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: numpy
+Description-Content-Type: text/markdown
+
+# timelined_array
+
+## Overview
+The TimelinedArray package provides a set of classes and utilities for working with time-indexed arrays. It extends the functionality of NumPy arrays to include time-based indexing and operations, making it easier to work with time-series data.
+
+## Classes
+### Timeline
+A subclass of np.ndarray that represents a timeline associated with the array. It includes methods for creating uniformly spaced timelines and calculating time steps.
+
+### Boundary
+An enumeration that defines inclusive and exclusive boundaries for time indexing.
+
+### TimeIndexer
+A class that provides methods for converting time values to array indices and for indexing arrays based on time.
+
+### TimeMixin
+A mixin class that adds time-related methods and properties to arrays, including methods for aligning, transposing, and moving axes.
+
+### TimePacker
+A class for packing arrays with their associated timelines. Usefull to plot data fast to matplotlib.
+
+### TimelinedArray
+A subclass of np.ndarray that includes a timeline and a time dimension. It provides methods for time-based indexing and operations.
+
+### MaskedTimelinedArray
+A subclass of np.ma.MaskedArray that includes a timeline and a time dimension. It provides methods for time-based indexing and operations on masked arrays.
+
+### Seconds
+A simple class for converting seconds to array indices based on a given sampling frequency.
+
+## Installation
+To install the TimelinedArray package, simply type in your environment activated console :
+```bash
+pip install timelined_array
+```
+
+The package can be found on PyPI at : https://pypi.org/project/timelined_array/ 
+
+## Usage
+
+### Imports
+```python
+from timelined_array import TimelinedArray, MaskedTimelinedArray, Boundary, Timeline
+```
+
+### Creating a TimelinedArray
+```python
+import numpy as np
+from timelined_array import TimelinedArray
+
+data = np.random.rand(100, 10)
+timeline = np.linspace(0, 10, 100)
+timelined_array = TimelinedArray(data, timeline=timeline, time_dimension=0)
+```
+### Time-based Indexing
+```python
+# Access data at a specific time
+data_at_time = timelined_array.itime[5.0]
+
+# Aligning arrays
+aligned_array = TimelinedArray.align_from_iterable([timelined_array, another_timelined_array])
+```
+
+
+### Masked TimelinedArray
+```python
+from timelined_array import MaskedTimelinedArray
+
+masked_data = np.ma.masked_array(data, mask=data > 0.5)
+masked_timelined_array = MaskedTimelinedArray(masked_data, timeline=timeline, time_dimension=0)
+```
+
+### Converting Seconds to Index
+```python
+masked_data.itime.time_to_index(5.0)
+```
+
+## Misc
+
+### License
+This package is licensed under the MIT License. See the LICENSE file for more details.
+
+### Contributing
+Contributions are welcome! Please submit a pull request or open an issue to discuss any changes.
+
+### Contact
+For any questions or issues, please contact the package maintainer.

timelined_array-0.0.6/README.md

@@ -0,0 +1,87 @@
+# timelined_array
+
+## Overview
+The TimelinedArray package provides a set of classes and utilities for working with time-indexed arrays. It extends the functionality of NumPy arrays to include time-based indexing and operations, making it easier to work with time-series data.
+
+## Classes
+### Timeline
+A subclass of np.ndarray that represents a timeline associated with the array. It includes methods for creating uniformly spaced timelines and calculating time steps.
+
+### Boundary
+An enumeration that defines inclusive and exclusive boundaries for time indexing.
+
+### TimeIndexer
+A class that provides methods for converting time values to array indices and for indexing arrays based on time.
+
+### TimeMixin
+A mixin class that adds time-related methods and properties to arrays, including methods for aligning, transposing, and moving axes.
+
+### TimePacker
+A class for packing arrays with their associated timelines. Usefull to plot data fast to matplotlib.
+
+### TimelinedArray
+A subclass of np.ndarray that includes a timeline and a time dimension. It provides methods for time-based indexing and operations.
+
+### MaskedTimelinedArray
+A subclass of np.ma.MaskedArray that includes a timeline and a time dimension. It provides methods for time-based indexing and operations on masked arrays.
+
+### Seconds
+A simple class for converting seconds to array indices based on a given sampling frequency.
+
+## Installation
+To install the TimelinedArray package, simply type in your environment activated console :
+```bash
+pip install timelined_array
+```
+
+The package can be found on PyPI at : https://pypi.org/project/timelined_array/ 
+
+## Usage
+
+### Imports
+```python
+from timelined_array import TimelinedArray, MaskedTimelinedArray, Boundary, Timeline
+```
+
+### Creating a TimelinedArray
+```python
+import numpy as np
+from timelined_array import TimelinedArray
+
+data = np.random.rand(100, 10)
+timeline = np.linspace(0, 10, 100)
+timelined_array = TimelinedArray(data, timeline=timeline, time_dimension=0)
+```
+### Time-based Indexing
+```python
+# Access data at a specific time
+data_at_time = timelined_array.itime[5.0]
+
+# Aligning arrays
+aligned_array = TimelinedArray.align_from_iterable([timelined_array, another_timelined_array])
+```
+
+
+### Masked TimelinedArray
+```python
+from timelined_array import MaskedTimelinedArray
+
+masked_data = np.ma.masked_array(data, mask=data > 0.5)
+masked_timelined_array = MaskedTimelinedArray(masked_data, timeline=timeline, time_dimension=0)
+```
+
+### Converting Seconds to Index
+```python
+masked_data.itime.time_to_index(5.0)
+```
+
+## Misc
+
+### License
+This package is licensed under the MIT License. See the LICENSE file for more details.
+
+### Contributing
+Contributions are welcome! Please submit a pull request or open an issue to discuss any changes.
+
+### Contact
+For any questions or issues, please contact the package maintainer.

{timelined_array-0.0.4 → timelined_array-0.0.6}/pyproject.toml

@@ -10,7 +10,7 @@ dependencies = [
 requires-python = ">=3.11"
 readme = "README.md"
 dynamic = []
-version = "0.0.4"
+version = "0.0.6"
 
 [project.license]
 text = "MIT"

{timelined_array-0.0.4 → timelined_array-0.0.6}/src/timelined_array/__init__.py

@@ -1,3 +1,3 @@
-__version__ = "0.0.4"
+__version__ = "0.0.6"
 
 from .time import TimelinedArray, MaskedTimelinedArray, Seconds, Boundary

{timelined_array-0.0.4 → timelined_array-0.0.6}/src/timelined_array/time.py

@@ -21,7 +21,7 @@ class TimeCompatibleProtocol(Protocol):
     def __array__(self) -> np.ndarray: ...
 
     @property
-    def shape(self) -> Tuple[int]: ...
+    def shape(self) -> Tuple[int, ...]: ...
 
     @property
     def ndim(self) -> int: ...
@@ -347,11 +347,11 @@ class TimeMixin:
     time_dimension: int
     timeline: Timeline
 
-    def _time_dimension_in_axis(self, axis: int | Tuple[int] | None) -> bool:
+    def _time_dimension_in_axis(self, axis: int | Tuple[int, ...] | None) -> bool:
         """Check if the time dimension is present in the specified axis.
 
         Args:
-            axis (int | Tuple[int] | None): The axis to check for the time dimension.
+            axis (int | Tuple[int, ...] | None): The axis to check for the time dimension.
 
         Returns:
             bool: True if the time dimension is present in the axis, False otherwise.
@@ -502,11 +502,11 @@ class TimeMixin:
 
         return index, final_timeline, final_time_dimension
 
-    def _get_indexed_times(self, index: int | Tuple[int] | slice | Tuple[slice] | List | np.ndarray):
+    def _get_indexed_times(self, index: int | Tuple[int, ...] | slice | Tuple[slice] | List | np.ndarray):
         """Get indexed times based on the provided index.
 
         Args:
-            index (int | Tuple[int] | slice | Tuple[slice] | List | np.ndarray): The index to retrieve times from.
+            index (int | Tuple[int, ...] | slice | Tuple[slice] | List | np.ndarray): The index to retrieve times from.
 
         Returns:
             np.ndarray: The indexed times based on the provided index.
@@ -531,12 +531,12 @@ class TimeMixin:
 
         return obj.shape == ()
 
-    def _finish_axis_removing_operation(self, result: TimeCompatibleProtocol, axis: int | Tuple[int] | None):
+    def _finish_axis_removing_operation(self, result: TimeCompatibleProtocol, axis: int | Tuple[int, ...] | None):
         """Finish axis removing operation.
 
         Args:
             result (TimeCompatibleProtocol): The result of the operation.
-            axis (int | Tuple[int] | None): The axis or axes to remove.
+            axis (int | Tuple[int, ...] | None): The axis or axes to remove.
 
         Returns:
             TimeCompatibleProtocol: The result after finishing the axis removing operation.
@@ -544,7 +544,7 @@ class TimeMixin:
 
         if not isinstance(result, np.ndarray):
             return result
-        if not self._is_single_element(result):
+        if self._is_single_element(result):
             return result.item()
         if self._time_dimension_in_axis(axis):
             return np.asarray(result)
@@ -641,6 +641,40 @@ class TimeMixin:
 
         return self.itime[start:][:element_nb]  # type: ignore
 
+    def shift_values(
+        self,
+        period: int | Tuple[int, ...] | slice | Tuple[slice, ...] | List | np.ndarray = 0,
+        axis=None,
+        time_period=True,
+    ):
+        """Shifts the values of the array along the specified axis by the given period.
+
+        Args:
+            period (int): The period by which to shift the values.
+            axis (int, optional): The axis along which to shift the values. Defaults to None.
+            time_period (bool, optional): If True, the shift is applied based on time. Defaults to True.
+
+        Returns:
+            numpy.ndarray: The array with shifted values.
+        """
+
+        if axis is None:
+            axis = self.time_dimension
+
+        indexer = []
+        for dim in range(len(self.shape)):
+            if dim == axis:
+                # make a new axis to account fo the axis loss of the .mean later
+                indexer.append(np.newaxis)
+            else:
+                # select all with slice(None) equivalent to ":"
+                indexer.append(slice(None))
+        indexer = tuple(indexer)
+
+        shift_area = self.itime.__getitem__(period) if time_period else self.__getitem__(period)
+
+        return self - np.repeat(shift_area.mean(axis=axis).__getitem__(tuple(indexer)), self.shape[axis], axis=axis)
+
     def swapaxes(self: TimeCompatibleProtocol, axis1: int, axis2: int):
         """Swap the two specified axes of the TimelinedArray.
 
@@ -701,12 +735,12 @@ class TimeMixin:
 
         return self.transpose()
 
-    def moveaxis(self: TimeCompatibleProtocol, source: int | Tuple[int], destination: int | Tuple[int]):
+    def moveaxis(self: TimeCompatibleProtocol, source: int | Tuple[int, ...], destination: int | Tuple[int, ...]):
         """Move the axis of the array to new positions.
 
         Args:
-            source (int or Tuple[int]): The source position(s) of the axis to move.
-            destination (int or Tuple[int]): The destination position(s) to move the axis to.
+            source (int or Tuple[int, ...]): The source position(s) of the axis to move.
+            destination (int or Tuple[int, ...]): The destination position(s) to move the axis to.
 
         Returns:
             TimeCompatibleProtocol: A new array with the axis moved to the specified destination.
@@ -777,11 +811,14 @@ class TimeMixin:
         # TimelinedArray.time_dimension and TimelinedArray.timeline are set. good to go
         return rolled_array
 
-    def mean(self: TimeCompatibleProtocol, axis: int | Tuple[int] | None = None, dtype=None, out=None, keepdims=False):
+    def mean(
+        self: TimeCompatibleProtocol, axis: int | Tuple[int, ...] | None = None, dtype=None, out=None, keepdims=False
+    ):
         """Calculates the mean along the specified axis.
 
         Args:
-            axis (int | Tuple[int] | None): Axis or axes along which to perform the mean operation. Default is None.
+            axis (int | Tuple[int, ...] | None): Axis or axes along which to perform the mean operation.
+                Default is None.
             dtype: Data-type to use in the computation.
             out: Output array where the result is stored.
             keepdims (bool): If True, the reduced dimensions are retained in the output array.
@@ -794,11 +831,13 @@ class TimeMixin:
         return self._finish_axis_removing_operation(result, axis)
 
     # Override other reduction methods similarly if needed
-    def sum(self: TimeCompatibleProtocol, axis: int | Tuple[int] | None = None, dtype=None, out=None, keepdims=False):
+    def sum(
+        self: TimeCompatibleProtocol, axis: int | Tuple[int, ...] | None = None, dtype=None, out=None, keepdims=False
+    ):
         """Calculate the sum along the specified axis.
 
         Args:
-            axis (int | Tuple[int] | None): Axis or axes along which a sum is performed.
+            axis (int | Tuple[int, ...] | None): Axis or axes along which a sum is performed.
                 The default is to sum over all the dimensions of the input array.
             dtype: The type of the returned array and of the accumulator in which the elements are summed.
                 If dtype is not specified, it defaults to the dtype of a, unless a has an integer dtype
@@ -818,12 +857,17 @@ class TimeMixin:
         return self._finish_axis_removing_operation(result, axis)
 
     def std(
-        self: TimeCompatibleProtocol, axis: int | Tuple[int] | None = None, dtype=None, out=None, ddof=0, keepdims=False
+        self: TimeCompatibleProtocol,
+        axis: int | Tuple[int, ...] | None = None,
+        dtype=None,
+        out=None,
+        ddof=0,
+        keepdims=False,
     ):
         """Calculate the standard deviation along the specified axis.
 
         Args:
-            axis (int or Tuple[int] or None): Axis or axes along which the standard deviation is computed.
+            axis (int or Tuple[int, ...] or None): Axis or axes along which the standard deviation is computed.
                 The default is to compute the standard deviation of the flattened array.
             dtype: Data-type of the result. If not provided, the data-type of the input is used.
             out: Output array with the same shape as input array, placed with the result.
@@ -841,13 +885,18 @@ class TimeMixin:
         return self._finish_axis_removing_operation(result, axis)
 
     def var(
-        self: TimeCompatibleProtocol, axis: int | Tuple[int] | None = None, dtype=None, out=None, ddof=0, keepdims=False
+        self: TimeCompatibleProtocol,
+        axis: int | Tuple[int, ...] | None = None,
+        dtype=None,
+        out=None,
+        ddof=0,
+        keepdims=False,
     ):
         """Calculate the variance along the specified axis.
 
         Args:
             self (TimeCompatibleProtocol): The input data.
-            axis (int | Tuple[int] | None): Axis or axes along which the variance is computed.
+            axis (int | Tuple[int, ...] | None): Axis or axes along which the variance is computed.
                 The default is to compute the variance of the flattened array.
             dtype: Data-type of the result. If not provided, the data-type of the input is used.
             out: Alternative output array in which to place the result.
@@ -1114,12 +1163,12 @@ class TimelinedArray(TimeMixin, np.ndarray, TimeCompatibleProtocol):
         return super().__array_function__(func, types, args, kwargs)
 
     def __getitem__(
-        self, index: int | Tuple[int] | slice | Tuple[slice] | List | np.ndarray
+        self, index: int | Tuple[int, ...] | slice | Tuple[slice, ...] | List | np.ndarray
     ) -> "TimelinedArray | np.ndarray":
         """Get item from TimelinedArray based on index or slice.
 
         Args:
-            index (int | Tuple[int] | slice | Tuple[slice] | List | np.ndarray): Index or slice to retrieve item.
+            index (int | Tuple[int, ...] | slice | Tuple[slice] | List | np.ndarray): Index or slice to retrieve item.
 
         Returns:
             TimelinedArray | np.ndarray: Indexed result based on the provided index.
@@ -1145,13 +1194,14 @@ class TimelinedArray(TimeMixin, np.ndarray, TimeCompatibleProtocol):
     def __repr__(self):
         """Return a string representation of the object with the class name and the array representation."""
 
-        return type(self).__name__ + np.array(self).__repr__()[5:]
+        # [5:] serves to remove the 'array' part for the original array repr string
+        return type(self).__name__ + np.asarray(self).__repr__()[5:]
 
     def __str__(self):
         """Return a string representation of the object by concatenating the class name with the string
         representation of the object as a NumPy array."""
 
-        return type(self).__name__ + np.array(self).__str__()
+        return type(self).__name__ + np.asarray(self).__str__()
 
     @staticmethod
     def align_from_iterable(iterable) -> "TimelinedArray":
@@ -1249,12 +1299,12 @@ class MaskedTimelinedArray(TimeMixin, np.ma.MaskedArray, TimeCompatibleProtocol)
         self.time_dimension = getattr(obj, "time_dimension", 0)
 
     def __getitem__(
-        self, index: int | Tuple[int] | slice | Tuple[slice] | List | np.ndarray
+        self, index: int | Tuple[int, ...] | slice | Tuple[slice] | List | np.ndarray
     ) -> "MaskedTimelinedArray | np.ma.MaskedArray":
         """Get item from the MaskedTimelinedArray based on the provided index.
 
         Args:
-            index (int | Tuple[int] | slice | Tuple[slice] | List | np.ndarray): The index or slice to retrieve.
+            index (int | Tuple[int, ...] | slice | Tuple[slice] | List | np.ndarray): The index or slice to retrieve.
 
         Returns:
             MaskedTimelinedArray | np.ma.MaskedArray: The masked array or MaskedTimelinedArray based on the index.

timelined_array-0.0.4/PKG-INFO

@@ -1,11 +0,0 @@
-Metadata-Version: 2.1
-Name: timelined_array
-Version: 0.0.4
-Summary: Manage easily 1 or multidimensionnal samples numpy arrays that are time related. Extends numpy without removing any of it's abilities on such arrays.
-Author-Email: Timothe Jost <timothe.jost@wanadoo.fr>
-License: MIT
-Requires-Python: >=3.11
-Requires-Dist: numpy
-Description-Content-Type: text/markdown
-
-# timelined_array

timelined_array-0.0.4/README.md

@@ -1 +0,0 @@
-# timelined_array