Functions to create time vectors

Time has a periodic nature due to the rotation of the earth and the position of the sun. This affects human behavior in various ways.

• Seasonality ... periodicity in a year (seasonal distinction)
• Daily periodicity ... periodicity in a day (distinction between day and night)
• Day of the week ... periodicity in a week (distinction between weekdays and holidays)

When dealing with these, it is desirable to vectorize with periodicity in mind. That is, at 23:59 on a given day, it is desirable that the value is close to 00:00 on the next day. To achieve this, the time is represented as a combination of cos and sin. This is called a time vector.

The base package has no NumPy dependency and supports timevec.builtin_math:

pip install timevec

Install the numpy extra when you use timevec.numpy or timevec.numpy_datetime64:

pip install "timevec[numpy]"

With the base install:

import datetime
import timevec.builtin_math as tv

dt = datetime.datetime(2020, 1, 1, 0, 0, 0)
vec = tv.year_vec(dt)
# (1.0, 0.0)

With the numpy extra:

import datetime
import timevec.numpy as tv

dt = datetime.datetime(2020, 1, 1, 0, 0, 0)
vec = tv.year_vec(dt)
# array([1., 0.])

• timevec.numpy provides functions that return numpy.ndarray.
• timevec.numpy_datetime64 provides functions that return numpy.datetime64.
• timevec.builtin_math provides functions that return tuple of float.

Almost same functions are provided in timevec.numpy, timevec.numpy_datetime64, and timevec.builtin_math. The difference is the return type.

year_vec(dt: datetime.datetime)

Create a time vector for a year. This is a vector that has periodicity like seasonality. (Summer, Autumn, Winter, Spring)

month_vec(dt: datetime.datetime)

Create a time vector for a month. This is a vector that has periodicity in a month. You can express periodicity such as the beginning of the month, the end of the month, and the salary day.

week_vec(dt: datetime.datetime)

Create a time vector for a week. This is a vector that has periodicity in a week. You can express periodicity such as weekdays and holidays.

day_vec(dt: datetime.datetime)

Create a time vector for a day. This is a vector that has periodicity in a day. You can express periodicity such as morning, noon, and night.

• long_time_vec ... datetime.min to datetime.max period
• millennium_vec ... one millennium (1000 years) period
• century_vec ... one century (100 years) period
• decade_vec ... one decade (10 years) period

This repository uses lefthook to run the same checks as CI locally, so problems surface before they reach CI.

# Install dependencies
uv sync

# Install the Git hooks (once; requires lefthook on your PATH)
lefthook install

Once installed, the hooks run automatically:

• pre-commit: uv run poe check
• pre-push: uv run poe check and uv run poe test

You can also run the checks manually:

uv run poe check
uv run poe test

CI still runs the full matrix (see .github/workflows/); the hooks only bring that feedback earlier on your machine.

BSD 3-Clause License