Metadata-Version: 2.5
Name: dataclocklib
Version: 0.3.0
Summary: Dataclock charts using matplotlib.
Project-URL: Repository, https://github.com/andyrids/dataclocklib
Project-URL: Issues, https://github.com/andyrids/dataclocklib/issues
Project-URL: Documentation, https://andyrids.github.io/dataclocklib/
Project-URL: Changelog, https://github.com/andyrids/dataclocklib/blob/main/CHANGELOG.md
Author-email: Andrew Ridyard <developer.surface832@passmail.com>
Maintainer-email: Andrew Ridyard <developer.surface832@passmail.com>
License-Expression: GPL-3.0-or-later
License-File: COPYRIGHT
License-File: LICENSE
Keywords: analysis,dataclock,matplotlib,visualisation
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Matplotlib
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: matplotlib>=3.10
Requires-Dist: pandas[parquet]>=3.0
Requires-Dist: pypalettes>=0.1.5
Provides-Extra: docs
Requires-Dist: myst-nb>=1.1.2; extra == 'docs'
Requires-Dist: sphinx-autobuild>=2024.10.3; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=3.0.2; extra == 'docs'
Requires-Dist: sphinx>=8.1.3; extra == 'docs'
Description-Content-Type: text/markdown

# Data Clock Visualisation Library

<!-- pyml disable-next-line line-length -->
![PyPI - Version](https://img.shields.io/pypi/v/dataclocklib?style=plastic) ![PyPI - Downloads](https://img.shields.io/pypi/dm/dataclocklib?style=plastic) ![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fandyrids%2Fdataclocklib%2Fmain%2Fpyproject.toml&style=plastic) ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/andyrids/dataclocklib/ci.yml?branch=main&style=plastic&logo=pytest&logoColor=%230A9EDC&label=pytest)
![GitHub deployments](https://img.shields.io/github/deployments/andyrids/dataclocklib/github-pages?style=plastic&&logo=sphinx&label=sphinx)

## Introduction

This library allows the user to create data clock graphs, using the matplotlib Python library.

Data clocks visually summarise temporal data in two dimensions, revealing seasonal or cyclical
patterns and trends over time. A data clock is a circular chart that divides a larger unit of time
into rings and subdivides it by a smaller unit of time into wedges, creating a set of temporal
bins.

These temporal bins are symbolised using graduated colors that correspond to a count or aggregated
value taking place in each time period.

The table below details the currently supported chart modes and the corresponding rings and wedges:

| Mode       | Rings            | Wedges           | Description                       |
|------------|------------------|------------------|-----------------------------------|
| YEAR_MONTH | Years            | Months           | Years / January - December.       |
| YEAR_WEEK  | Years            | Weeks            | Calendar years / weeks 1 - 52.    |
| WEEK_DAY   | Weeks            | Days of the week | ISO weeks / Monday - Sunday.      |
| DOW_HOUR   | Days of the week | Hour of day      | Monday - Sunday / 24 hours.       |
| DAY_HOUR   | Days             | Hour of day      | Days 1 - 366 / 24 hours.          |

The full documentation can be viewed on the project [GitHub Page](https://andyrids.github.io/dataclocklib/).

### Example charts

Chart examples have been generated using UK Department for Transport data 2010 - 2015.

```python
import pandas as pd
from dataclocklib.charts import dataclock

data = pd.read_parquet(
    "https://raw.githubusercontent.com/andyrids/dataclocklib/main/tests/data/traffic_data.parquet.gzip"
)

chart_data, fig, ax = dataclock(
    data=data,
    date_column="Date_Time",
    mode="DOW_HOUR",
    spine_color="darkslategrey",
    grid_color="black",
    default_text=False,
)
```

![Data clock chart](https://raw.githubusercontent.com/andyrids/dataclocklib/main/docs/source/_static/images/sphinx_guide_chart_1.png)

```python
import pandas as pd
from dataclocklib.charts import dataclock

data = pd.read_parquet(
    "https://raw.githubusercontent.com/andyrids/dataclocklib/main/tests/data/traffic_data.parquet.gzip"
)

chart_data, fig, ax = dataclock(
    data=data,
    date_column="Date_Time",
    mode="DOW_HOUR",
    spine_color="darkslategrey",
    grid_color="black",
    default_text=True,
)
```

![Data clock chart](https://raw.githubusercontent.com/andyrids/dataclocklib/main/docs/source/_static/images/sphinx_guide_chart_2.png)

```python
import pandas as pd
from dataclocklib.charts import dataclock

data = pd.read_parquet(
    "https://raw.githubusercontent.com/andyrids/dataclocklib/main/tests/data/traffic_data.parquet.gzip"
)

chart_data, fig, ax = dataclock(
    data=data,
    date_column="Date_Time",
    mode="DOW_HOUR",
    default_text=True,
    spine_color="darkslategrey",
    grid_color="black",
    chart_title="**CUSTOM TITLE**",
    chart_subtitle="**CUSTOM SUBTITLE**",
    chart_period="**CUSTOM PERIOD**",
    chart_source="Source: UK Department for Transport",
    dpi=150,
)
```

![Data clock chart](https://raw.githubusercontent.com/andyrids/dataclocklib/main/docs/source/_static/images/sphinx_guide_chart_3.png)

```python
import pandas as pd
from dataclocklib.charts import dataclock

data = pd.read_parquet(
    "https://raw.githubusercontent.com/andyrids/dataclocklib/main/tests/data/traffic_data.parquet.gzip"
)

chart_data, fig, ax = dataclock(
    data=data.query("Date_Time.dt.year.eq(2010)"),
    date_column="Date_Time",
    agg_column="Number_of_Casualties",
    agg="sum",
    mode="DOW_HOUR",
    cmap_name="X26",
    cmap_reverse=True,
    spine_color="honeydew",
    grid_color="honeydew",
    default_text=True,
    chart_title="UK Traffic Accident Casualties",
    chart_subtitle=None,
    chart_period="Period: 2010",
    chart_source="Source: https://data.dft.gov.uk/road-accidents-safety-data/dft-road-casualty-statistics-collision-last-5-years.csv",
    dpi=300,
)
```

![Data clock chart](https://raw.githubusercontent.com/andyrids/dataclocklib/main/docs/source/_static/images/sphinx_guide_chart_4.png)

## Installation

You can install using `pip`:

```bash
python -m pip install dataclocklib
```

To install from GitHub use:

```bash
python -m pip install git+https://github.com/andyrids/dataclocklib.git
```

## Development Installation

Astral **uv** is used as the Python package manager. To install **uv** see the installation
guide @ [uv documentation](https://docs.astral.sh/uv/getting-started/installation/).

Clone the repository:

```bash
git clone git@github.com:andyrids/dataclocklib.git
cd dataclocklib
```

Sync the dependencies, including the dev dependency group and optional dependencies with uv:

```bash
uv sync --all-extras
```

Activate the virtual environment:

```bash
. .venv/bin/activate
```

Common development tasks are [just](https://github.com/casey/just) recipes (run `just` to list them):

```bash
just setup      # uv sync --all-extras, install the prek git hooks, update .secrets.baseline
just coverage   # run the tests with a coverage report
```

### Sphinx documentation

Build the HTML documentation into `docs/build/html` (warnings are treated as errors):

```bash
just docs
```

Serve it locally with live reload, or remove the build output:

```bash
just docs-serve
just docs-clean
```
