Helpers
TimeNDArray
Bases: ndarray, Generic[T]
Time-aware numpy array that tracks visible data length for backtesting.
This class extends numpy.ndarray to provide time-series awareness for backtesting applications. It maintains an internal index (_i) that represents how much of the array is "visible" at any given time step, allowing for efficient iteration over historical data without copying.
Key features: - Maintains current time index (_i) for progressive data access - Supports various indexing modes (integer, slice, boolean, array) - Handles negative indices relative to current time index - Provides array conversion methods that respect time visibility - Supports numpy array operations while maintaining time awareness
The class is designed to be used in backtesting where data becomes available progressively over time, and only data up to the current time step should be visible to the strategy.
Example
import numpy as np
data = np.array([1, 2, 3, 4, 5])
time_arr = TimeNDArray.from_array(data)
print(time_arr._i) # Shows full length
5
print(time_arr.visible()) # Array up to _i
[1 2 3 4 5]
time_arr._i = 3 # Only first 3 elements visible
print(len(time_arr)) # Shows 3
3
print(time_arr[:2]) # First 2 visible elements
[1 2]
__array__(dtype=None)
Convert to numpy array, returning only visible portion.
This method is called during numpy array conversions and ensures that only the visible portion of the data (up to _i) is returned.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dtype
|
optional
|
Target dtype for conversion. |
None
|
Returns:
| Type | Description |
|---|---|
|
np.ndarray: Visible portion of the array as numpy array. |
__array_finalize__(obj)
Initialize or update the time index when array is created or modified.
This method is called automatically by numpy when the array is created or sliced. It ensures that the time index (_i) is properly maintained across operations.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
Any
|
The object that triggered array finalization. |
required |
__getitem__(idx)
Advanced indexing with time-aware bounds checking.
This method handles various indexing modes while respecting the current time index (_i) for bounds checking. It supports: - Integer indexing (with negative index conversion) - Slice indexing (interpreted relative to _i) - Boolean indexing (masked to visible portion) - Array indexing (with negative index conversion) - Tuple indexing (for multi-dimensional arrays)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
idx
|
Index specification (int, slice, array, or tuple). |
required |
Returns:
| Type | Description |
|---|---|
|
TimeNDArray or np.ndarray: Indexed result with appropriate time awareness. |
Raises:
| Type | Description |
|---|---|
IndexError
|
If indices are out of visible bounds. |
Note
Negative indices are converted relative to the current visible length (_i), not the full array length.
__iter__()
Iterate over visible elements only.
Yields:
| Type | Description |
|---|---|
|
Elements from the array up to the current index. |
__len__()
Get the current visible length of the array.
Returns:
| Name | Type | Description |
|---|---|---|
int |
int
|
Current visible length (value of _i). |
__repr__()
String representation showing only visible data.
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
String representation of the visible portion. |
__str__()
String conversion showing only visible data.
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
String representation of the visible portion. |
from_array(arr)
classmethod
Create a TimeNDArray from a regular numpy array.
This class method provides a convenient way to convert a standard numpy array to a TimeNDArray with full visibility initialized.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
arr
|
NDArray[T]
|
Input numpy array to convert. |
required |
Returns:
| Type | Description |
|---|---|
TimeNDArray[T]
|
TimeNDArray[T]: New TimeNDArray instance with full visibility. |
Example
data = np.array([1, 2, 3])
time_arr = TimeNDArray.from_array(data)
print(time_arr._i)
3
visible()
Return a plain numpy array view of the visible portion.
This method provides a clean way to get the visible portion of the array as a standard numpy array, suitable for operations that don't need time awareness.
Returns:
| Type | Description |
|---|---|
NDArray[T]
|
npt.NDArray[T]: Visible portion of the data as numpy array. |
Example
time_arr._i = 3
print(time_arr.visible())
[1 2 3]
Source code
src/quantex/helpers.py- Utility functions for trading strategies