isoperiod#
A small, dependency-free Python library for working with ISO 8601 periods: the repeating intervals that give timeseries data its sampling resolution and periodicity.
Includes customised ISO 8601 intervals which can have an offset from their natural boundary, such as a hydrological day running 09:00 to 09:00.
Current version: 1.2.1
Build a period from ISO 8601 string formats: e.g. "PT15M", "P1D", "P1Y"
Shift every interval boundary off its natural position: e.g. a day that starts at 09:00, or a year that starts in October.
Every interval on the timeline has an integer ordinal, so interval arithmetic is just integer arithmetic.
Ask whether a timestamp sits on a period boundary, and whether one period nests cleanly inside another.
Pin the grid to a chosen datetime, so a known start date defines where the intervals fall.
Pure Python on top of datetime, with helpers for handing periods to Polars.
Why isoperiod?#
Timeseries data is generally measured on a structured grid: every 15 minutes, every day, every water year. isoperiod makes that grid a first-class object to help enforce rules and properties that can help keep your timeseries code in check.
Core Period object. A
Periodsplits the whole timeline into consecutive, numbered intervals, and maps freely between a datetime and the interval that contains it.Offsets built in. Hydrological days, water years, sensors reporting at five past the quarter hour - all expressible and comparable with each other.
Domain knowledge. Built by software engineers and data scientists at UKCEH from years of experience with hydrological and environmental data.
Small and dependency-free. Standard library only, so it drops into any project.
isoperiod is the period engine behind Time-Stream, and is published separately so it can be used on its own.
Community#
Developed at UKCEH, welcoming community engagement and contributions.
License#
This project is licensed under the MIT.