ts - Time Series

The ts module provides time series primitives with datetime validation and timezone support. This is Layer 2 of the architecture.

Key Features

DatetimeList: A validated list of datetime objects
TsVector: A time series vector with datetime index and numeric values
Timezone support: Convert between timezones
Efficient storage: Store as base + deltas for compact serialization

Classes

TsVector

class pyswark.ts.tsvector.TsVector(*, index: DatetimeList, values: Vector)

Bases: BaseModel

A time series with datetime index and numeric values.

Combines a DatetimeList index with a Vector of values, ensuring they have matching lengths.

Parameters:

index (DatetimeList or array-like) – The datetime index.
values (Vector or array-like) – The numeric values.

Example

>>> from pyswark.ts.tsvector import TsVector
>>> ts = TsVector(
...     index=['2024-01-01', '2024-01-02', '2024-01-03'],
...     values=[100.0, 101.5, 99.8]
... )
>>> print(len(ts))  # 3

property dt

index: DatetimeList

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

values: Vector

DatetimeList

class pyswark.core.models.datetime.DatetimeList(inputs=None)

Bases: ConverterModel

A validated list of datetimes.

Efficiently stores a list of datetimes as a base datetime plus deltas, enabling compact serialization.

Parameters:: inputs (Inputs or array-like) – The datetime data.

dt

The datetime array (dtype datetime64).

Type:: numpy.ndarray

basedt

The base datetime.

Type:: numpy.datetime64

deltas

The delta offsets from base.

Type:: numpy.ndarray

Example

>>> from pyswark.core.models.datetime import DatetimeList
>>> dates = DatetimeList(['2024-01-01', '2024-01-02', '2024-01-03'])
>>> print(len(dates))  # 3
>>> print(dates.dt)

astype(dtype)

property basedt: Return the base datetime.

static convert(inputs: Inputs) → dict[str, Union[pyswark.core.models.datetime.Datetime, numpy.ndarray]]

property deltas: Return the delta offsets.

property dt: Return the datetime array.

property dtype: Return the datetime dtype.

inputs: Inputs

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

resample(to): return sampled Datetimelist

Datetime

class pyswark.core.models.datetime.Datetime(*args, data: str, dtype: str | None = None, tzname: str | None = None)

Bases: BaseInputs

A validated datetime with timezone support.

Provides consistent datetime handling with timezone conversion and dtype specification.

Parameters:

data (str) – The datetime string.
dtype (str, optional) – The numpy datetime64 resolution (e.g., ‘s’, ‘ms’, ‘D’).
tzname (str, optional) – The timezone name (e.g., ‘UTC’, ‘US/Eastern’).

Example

>>> dt = Datetime('2024-01-15T10:30:00', dtype='s', tzname='UTC')
>>> dt_eastern = dt.toTimezone('US/Eastern')

after()

classmethod after_data_dtype(data, dtype)

static after_dtype(dtype)

classmethod after_tzname(tzname, data)

classmethod before_data(data) → str

classmethod before_dtype(dtype)

data: str

property datetime

property dt

dtype: str | None

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod now(tzname='UTC')

toDtype(dtype)

toTimezone(tzname)

tzname: str | None

Usage Examples

Creating a TsVector

from pyswark.ts.tsvector import TsVector

# Create from lists
ts = TsVector(
    index=['2024-01-01', '2024-01-02', '2024-01-03'],
    values=[100.0, 101.5, 99.8]
)

print(len(ts))        # 3
print(ts.dt)          # datetime64 array
print(ts.values)      # Vector object

Working with DatetimeList

from pyswark.core.models.datetime import DatetimeList

# Create from strings
dates = DatetimeList(['2024-01-01', '2024-01-02', '2024-01-03'])
print(len(dates))     # 3
print(dates.dt)       # array of datetime64

# Create from datetime objects
import datetime
dates2 = DatetimeList([
    datetime.datetime(2024, 1, 1),
    datetime.datetime(2024, 1, 2),
])

# Resample to different resolution
monthly = dates.resample('M')

Working with Datetime

from pyswark.core.models.datetime import Datetime

# Create with timezone
dt = Datetime('2024-01-15T10:30:00', dtype='s', tzname='UTC')

# Convert to another timezone
dt_eastern = dt.toTimezone('US/Eastern')

# Get current time
now = Datetime.now(tzname='UTC')

Serialization

Time series objects are fully serializable:

from pyswark.ts.tsvector import TsVector
from pyswark.lib.pydantic import ser_des

ts = TsVector(
    index=['2024-01-01', '2024-01-02'],
    values=[100.0, 101.5]
)

# Serialize
json_str = ser_des.toJson(ts)

# Deserialize
restored = ser_des.fromJson(json_str)