ukceh-time-stream 4.0.0__tar.gz

ukceh_time_stream-4.0.0/.editorconfig

@@ -0,0 +1,33 @@
+# https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{html,css,js,json,sh,yml,yaml}]
+indent_size = 2
+
+[*.bat]
+indent_style = tab
+end_of_line = crlf
+
+[LICENSE]
+insert_final_newline = false
+
+# Ignore binary or generated files
+[*.{png,jpg,gif,ico,woff,woff2,ttf,eot,svg,pdf}]
+charset = unset
+end_of_line = unset
+indent_style = unset
+indent_size = unset
+trim_trailing_whitespace = unset
+insert_final_newline = unset
+max_line_length = unset
+
+[*.{diff,patch}]
+trim_trailing_whitespace = false

ukceh_time_stream-4.0.0/.githooks/pre-commit

@@ -0,0 +1,47 @@
+#!/bin/sh
+#
+# Pre-commit hook: runs ruff format and lint checks via uv.
+# Requires uv on PATH: https://docs.astral.sh/uv/getting-started/installation/
+#
+# Installed automatically by post-generation hook via:
+#   git config core.hooksPath .githooks
+#
+# To install manually in an existing clone:
+#   make install-hooks
+
+# Redirect output to stderr.
+exec 1>&2
+
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+format_err=0
+check_err=0
+err=0
+
+echo 'Running "uv run ruff format --check"'
+uv run ruff format --check
+
+if [ "$?" -eq 1 ]; then
+    format_err=1
+    err=1
+fi
+
+echo 'Running "uv run ruff check"'
+uv run ruff check
+
+if [ "$?" -eq 1 ]; then
+    check_err=1
+    err=1
+fi
+
+if [ "${format_err}" -eq 1 ] ; then
+    echo "${RED}Run \"ruff format\" before committing${NC}"
+fi
+
+if [ "${check_err}" -eq 1 ] ; then
+    echo "${RED}Correct ruff errors before committing${NC}"
+fi
+
+if [ "${err}" -eq 1 ] ; then
+    exit 1
+fi

ukceh_time_stream-4.0.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,61 @@
+name: Bug Report
+description: Something isn't working as expected.
+title: "BUG: "
+labels: [bug]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the bug
+      description: What happened? What did you expect to happen?
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: Minimal steps to trigger the bug.
+      placeholder: |
+        1. Install with `uv pip install ukceh-time-stream`
+        2. Run `...`
+        3. See error
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: "My Package version"
+      placeholder: "0.1.0"
+    validations:
+      required: true
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: "3.13"
+    validations:
+      required: true
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options:
+        - macOS
+        - Linux
+        - Windows
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Logs, tracebacks, screenshots, or anything else that helps.
+    validations:
+      required: false

ukceh_time_stream-4.0.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

ukceh_time_stream-4.0.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,30 @@
+name: Feature Request
+description: Suggest something new.
+title: "FEAT: "
+labels: [enhancement]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the feature
+    validations:
+      required: true
+  - type: textarea
+    id: motivation
+    attributes:
+      label: Motivation
+      description: What problem does this solve? What's the use case?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+    validations:
+      required: false
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+    validations:
+      required: false

ukceh_time_stream-4.0.0/.github/dependabot.yml

@@ -0,0 +1,23 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+    open-pull-requests-limit: 5
+    groups:
+      all-actions:
+        patterns:
+          - "*"
+
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      all-dependencies:
+        patterns:
+          - "*"

ukceh_time_stream-4.0.0/.github/pull_request_template.md

@@ -0,0 +1,9 @@
+## Issue ticket number and link
+
+## Overview
+
+<!-- 1-3 sentences of problem this PR addresses -->
+
+## Main changes
+
+<!-- List of the core changes to point reviewers towards -->

ukceh_time_stream-4.0.0/.github/workflows/pipeline.yml

@@ -0,0 +1,151 @@
+name: Pipeline
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - develop
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  actions: read
+
+  pages: write
+  id-token: write
+
+
+jobs:
+
+  test-python:
+    uses: NERC-CEH/dri-cicd/.github/workflows/test-python.yml@main
+    with:
+      use_uv: true
+      use_pyright: true
+      coverage_threshold: 90
+
+
+  build-docs:
+    uses: NERC-CEH/dri-cicd/.github/workflows/build-docs.yml@main
+    with:
+      use_uv: true
+      pages_artifact_name: pages-artifact
+
+  deploy-docs:
+    needs: [build-docs]
+    if: github.ref == 'refs/heads/main'
+    uses: NERC-CEH/dri-cicd/.github/workflows/deploy-docs.yml@main
+    with:
+      pages_artifact_name: pages-artifact
+
+  release-ready:
+    if: github.event_name == 'pull_request' && github.base_ref == 'main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          fetch-depth: 0
+
+      - name: Check version bump and changelog
+        run: |
+          BASE_VER=$(git show origin/main:pyproject.toml | grep '^version' | sed 's/.*"\(.*\)"/\1/')
+          NEW_VER=$(grep '^version' pyproject.toml | sed 's/.*"\(.*\)"/\1/')
+
+          if [ "$BASE_VER" = "$NEW_VER" ]; then
+            echo "ERROR: merges to main require a version bump (current: $NEW_VER)"
+            exit 1
+          fi
+
+          echo "Version bumped: $BASE_VER -> $NEW_VER"
+
+          CHANGELOG="CHANGELOG/${NEW_VER}.md"
+
+          if [ ! -f "$CHANGELOG" ]; then
+            echo "ERROR: $CHANGELOG not found"
+            exit 1
+          fi
+
+          if grep -q "<!-- Add release notes here -->" "$CHANGELOG"; then
+            echo "ERROR: $CHANGELOG still contains the stub placeholder"
+            exit 1
+          fi
+
+          LINES=$(tail -n +2 "$CHANGELOG" | grep -vc '^$')
+          if [ "$LINES" -eq 0 ]; then
+            echo "ERROR: $CHANGELOG has no content beyond the heading"
+            exit 1
+          fi
+
+          echo "Changelog looks good"
+
+  release:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: [test-python]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      released: ${{ steps.release.outputs.released }}
+    steps:
+      - uses: actions/checkout@v7.0.1
+
+      - uses: astral-sh/setup-uv@v10.3.0
+
+      - name: Configure git identity
+        run: |
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git config user.name "github-actions[bot]"
+
+      - name: Release
+        id: release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION=$(grep '^version' pyproject.toml | sed 's/.*"\(.*\)"/\1/')
+          if git ls-remote --tags origin | grep -q "refs/tags/v$VERSION$"; then
+            echo "Tag v$VERSION already exists — skipping release"
+            exit 0
+          fi
+          make release
+          echo "released=true" >> "$GITHUB_OUTPUT"
+
+  build-dist:
+    needs: [release]
+    if: needs.release.outputs.released == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@v10.3.0
+        with:
+          enable-cache: false
+
+      - name: Build
+        run: uv build
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: [build-dist]
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ukceh-time-stream
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ukceh_time_stream-4.0.0/.gitignore

@@ -0,0 +1,168 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+.benchmarks/
+benchmark*.svg
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+# Using the plot directive from code in src/examples will copy outputs to docs/src/examples.  No need to commit this.
+docs/src
+docs/source/api/_api/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+.idea/
+
+# VSCode
+.vscode
+
+CLAUDE.md

ukceh_time_stream-4.0.0/CHANGELOG/1.0.0.md

@@ -0,0 +1,45 @@
+# 1.0.0
+
+## 24/06/2026
+
+After over a year of active development within UKCEH's FDRI programme, time-stream 1.0.0 marks the first stable,
+versioned public release. The library provides a high-level API for working with environmental time series data
+built on [Polars](https://pola.rs/), with a focus maintaining the integrity of the temporal properties time series data.
+
+## Features
+
+### Core
+
+- **`TimeFrame`** - the central data structure wrapping a Polars DataFrame  with an associated periodicity and
+time anchor, enforcing a consistent schema for time series operations.
+- **`Period`** - a rich period/frequency abstraction supporting both fixed-duration (sub-daily through multi-year)
+and calendar-aligned (monthly, annual) periods, with ISO 8601 duration support.
+
+### Flagging
+
+- Bitwise and categorical flag systems for recording QC and processing decisions alongside the data.
+- Flag columns can be attached to any `TimeFrame` column.
+- Support for encoding and decoding flag values, and auto-generation of bitwise flag integers from a list of named
+categories.
+- Filter a `TimeFrame` by flag values to subset data based on QC or processing state.
+
+### Aggregation
+
+- Standard temporal aggregation via `TimeFrame.aggregate()`, with support for custom time windows, time anchoring,
+and configurable missing-data criteria.
+- Rolling aggregation via `TimeFrame.rolling_aggregate()` with trailing, leading, and centre alignment.
+- Built-in aggregation functions, including: mean, sum, min, max, standard deviation, angular mean, and count.
+
+### Quality Control
+
+- Extensible QC framework (`QCCheck`) with a registration system allowing custom checks to be defined and reused by
+name.
+- Built-in checks, including: range, flatline, and spike detection.
+- QC results returned as a Polars `Series` or written directly into a flag column on the `TimeFrame`.
+
+### Infilling
+
+- Infill framework (`InfillMethod`) for filling gaps in time series, with a registration system for custom methods.
+- Built-in interpolation methods, including: linear, quadratic, cubic, B-spline, Akima, and PCHIP.
+- Alternative-data infill from a secondary column or DataFrame, with an optional correction factor.
+- Configurable maximum gap size and observation interval constraints to limit where infilling is applied.

ukceh_time_stream-4.0.0/CHANGELOG/1.1.0.md

@@ -0,0 +1,28 @@
+# 1.1.0
+
+This release adds a new dynamic alternative-data infilling method, a helper for renaming the time column, and
+simplifies the public API by replacing enums with string literals. It also includes routine dependency updates.
+
+## Features
+
+### Infilling
+
+- **`AltDataDynamic`** - a new alternative-data infill method that derives a *dynamic* correction factor from data
+windows either side of each gap, rather than a single static factor.
+
+### Core
+
+- **`TimeFrame.rename_time_column()`** - rename the time column on a `TimeFrame` while preserving its temporal
+properties.
+
+## Changes
+
+- Public API enums (e.g. time anchor, closed interval, missing criteria, duplicate options, alignment) have been
+replaced by `Literal[...]` string values, simplifying usage.
+
+## Maintenance
+
+- Added automated `uv` dependency updates via Dependabot.
+- Numerous dependency bumps across the project and documentation.
+- Resolved deprecation warnings in Sphinx documentation builds and fixed pyright type-checking issues following
+dependency updates.

ukceh_time_stream-4.0.0/CHANGELOG/1.1.1.md

@@ -0,0 +1,10 @@
+# 1.1.1
+
+This release fixes incorrect type hints on the `missing_criteria` parameter.
+
+## Bug fixes
+
+- **`missing_criteria` type hints** - the first element of the `missing_criteria` tuple in `TimeFrame.aggregate()`,
+  `TimeFrame.rolling_aggregate()`, and the internal pipeline classes (`AggregationPipeline`,
+  `StandardAggregationPipeline`, `RollingAggregationPipeline`) was incorrectly typed as `str`. It is now correctly typed
+  as `MissingCriteria`.

ukceh_time_stream-4.0.0/CHANGELOG/1.2.0.md

@@ -0,0 +1,19 @@
+# 1.2.0
+
+This release adds a new `nth` aggregation method for selecting a value at a fixed position within an aggregation
+period or rolling window. It also includes a code fix for deprecation warnings raised by updated dependencies,
+alongside routine dependency updates.
+
+## Features
+
+### Aggregation
+
+- **`Nth`** - a new aggregation function that selects the value (and its timestamp) at a fixed 1-based position
+within each aggregation period, e.g. always taking the reading at a particular time of day. Also usable with
+`TimeFrame.rolling_aggregate()` to pull a value from a fixed position relative to each timestamp.
+
+## Maintenance
+
+- Updated code in the flags and infill modules to resolve deprecation warnings raised by updated dependencies.
+- Added automated `uv` dependency updates via Dependabot.
+- Numerous dependency and GitHub Actions bumps across the project.

ukceh_time_stream-4.0.0/CHANGELOG/1.2.1.md

@@ -0,0 +1,8 @@
+# 1.2.1
+
+This is a small release with a documentation branding update and routine dependency updates.
+
+## Maintenance
+
+- Updated the UKCEH logo and related branding assets used in the documentation site.
+- Bumped `uv` dependencies and GitHub Actions across the project.

ukceh_time_stream-4.0.0/CHANGELOG/2.0.0.md

@@ -0,0 +1,46 @@
+# 2.0.0
+
+This release extracts the period/frequency handling into a standalone package, [`isoperiod`](https://github.com/NERC-CEH/isoperiod),
+and Time-Stream now depends on it rather than shipping its own `Period` implementation. This removes `Period`
+from the `time_stream` namespace and tightens the accepted duration/offset string syntax, so it is a breaking
+release. Runtime dependencies have also been trimmed to just Polars, NumPy, SciPy, and `isoperiod`.
+
+## Breaking changes
+
+### Period moved to `isoperiod`
+
+- The `Period` class and all period parsing/arithmetic have been removed from Time-Stream and are now provided
+by the separate `isoperiod` package. Replace `from time_stream import Period` with `from isoperiod import Period`.
+- `TimeFrame.resolution`, `TimeFrame.alignment` and `TimeFrame.periodicity` now return `isoperiod.Period`
+objects. The public behaviour is the same; only the import path of the type has changed.
+- The period exceptions have been removed from `time_stream.exceptions`: `PeriodError`, `PeriodParsingError`
+and `PeriodValidationError` now live in `isoperiod.exceptions` (and re-exported from `isoperiod`).
+`PeriodConfigError` has been removed entirely.
+
+### Duration and offset string syntax
+
+- Time components in a duration or offset string must now be preceded by `T`, following ISO 8601 strictly.
+`TimeFrame(df, "time", resolution="P1D", offset="+9H")` must become `offset="+T9H"`; `"P1Y+9M9H"` must become
+`"P1Y+9MT9H"`. Strings that only use date components (e.g. `"+9M"`) are unaffected.
+- `Period.count()` now returns `int | None` (`None` when there is no fixed count, e.g. days in a month) instead
+of `0`. Code that compared the result with `> 0` should check `is not None` first.
+
+### Dependencies
+
+- Removed unused runtime dependencies: `config`, `pydantic`, `isodate` and `altair`.
+- `pandas`, `matplotlib` and `pyarrow` are no longer runtime dependencies. They are only used by the
+documentation examples and are now in the `examples` dependency group. Installing `time-stream` no longer pulls
+them in transitively.
+
+## Changes
+
+- API reference docstrings now contain runnable, checked examples (`>>>` doctests) in place of illustrative
+snippets.
+
+## Maintenance
+
+- The user guide's example code has moved from `src/time_stream/examples/` to `docs/source/examples/`, so it is
+no longer shipped in the wheel. Examples are executed as part of the test suite
+- (`tests/time_stream/examples/test_examples.py`) and the docstring examples run under pytest's `--doctest-modules`.
+- Fixed several stale period strings and a typo in the `TimeFrame` docstring examples.
+- Numerous dependency and GitHub Actions bumps across the project.