Metadata-Version: 2.4
Name: echotime
Version: 0.17.0
Summary: Explainable structural similarity for time series and time-series datasets.
Author-email: Zipeng Wu <zxw365@student.bham.ac.uk>
License-Expression: MIT
Project-URL: Homepage, https://zipengwu365.github.io/EchoWave/
Project-URL: Documentation, https://zipengwu365.github.io/EchoWave/guide/
Project-URL: Repository, https://github.com/ZipengWu365/EchoWave
Project-URL: Issues, https://github.com/ZipengWu365/EchoWave/issues
Keywords: time-series,similarity,dataset-similarity,analog-search,structural-similarity,agent-tools,explainable-ai,irregular-sampling,event-stream,longitudinal,wearable,clinical,traffic,markets
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22
Requires-Dist: scipy>=1.8
Provides-Extra: io
Requires-Dist: pandas>=2.0; extra == "io"
Provides-Extra: parquet
Requires-Dist: pandas>=2.0; extra == "parquet"
Requires-Dist: pyarrow>=14.0; extra == "parquet"
Provides-Extra: mixed-stack
Requires-Dist: numpy<2.2,>=1.22; extra == "mixed-stack"
Requires-Dist: scipy<1.15,>=1.8; extra == "mixed-stack"
Requires-Dist: pandas<2.3,>=2.0; extra == "mixed-stack"
Requires-Dist: numba<0.62,>=0.58; extra == "mixed-stack"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pandas>=2.0; extra == "dev"
Dynamic: license-file

# EchoTime

**Explainable time-series similarity for humans and agents.**

[![PyPI version](https://img.shields.io/pypi/v/echotime?style=flat-square)](https://pypi.org/project/echotime/)
[![Python versions](https://img.shields.io/pypi/pyversions/echotime?style=flat-square)](https://pypi.org/project/echotime/)
[![License: MIT](https://img.shields.io/badge/license-MIT-ffc83d?style=flat-square)](LICENSE)
[![Status: Beta](https://img.shields.io/badge/status-beta-2f6bff?style=flat-square)](https://github.com/ZipengWu365/EchoWave)
[![Docs: GitHub Pages](https://img.shields.io/badge/docs-GitHub%20Pages-2f6bff?style=flat-square)](https://zipengwu365.github.io/EchoWave/)

EchoTime compares time series and time-series datasets, explains why they match or differ, and emits compact JSON plus shareable HTML reports.

## Why this package exists

Most time-series tooling helps after you decide what to model. EchoTime helps one step earlier: compare two signals clearly, compare two datasets structurally, and emit a result that a human or an agent can actually act on.

## Quickstart

```bash
pip install echotime
python -c "import numpy as np; from echotime import compare_series; x=np.sin(np.linspace(0,8*np.pi,128)); y=np.sin(np.linspace(0,8*np.pi,128)+0.2); print(compare_series(x,y).to_summary_card_markdown())"
```

Expected output starts like this:

```text
# EchoTime similarity summary
overall similarity: ...
top components: shape similarity, trend similarity, spectral similarity
```

## Use your own data

EchoTime is meant to run on real files, not just toy arrays.

- single numeric column -> `profile_series(...)`
- wide table with one `timestamp` column and one or more numeric columns -> `profile_dataset(df, domain=...)`
- irregular long table -> rename columns to `subject`, `timestamp`, `channel`, `value`, then call `profile_dataset(...)`
- two columns to compare -> `compare_series(df["left"], df["right"])`

Tabular inputs are auto-detected from names such as `timestamp` / `time`, `value` / `measurement`, `channel` / `sensor` / `metric`, and `subject` / `patient` / `participant`.

```python
from pathlib import Path

import pandas as pd
from echotime import profile_dataset

df = pd.read_csv("my_timeseries.csv").rename(columns={"date": "timestamp"})
profile = profile_dataset(df, domain="energy")
print(profile.to_summary_card_markdown())
Path("my_dataset_report.html").write_text(profile.to_html_report(), encoding="utf-8")
```


## What ships in v0.17.0

- compare-first public package surface
- agent-ready JSON wrappers with stable envelopes
- GitHub Pages-ready docs bundle
- local live demo for pasted arrays
- starter datasets, notebooks, and flagship demos
- compatibility presets and environment doctor guidance for mixed scientific stacks

## Common entry points

- `echotime-demo --open-browser`
- `echotime --guide quickstart`
- `echotime --guide doctor`
- `echotime --export-pages docs`

## Links

- README: `README.md`
- Start here: `START_HERE.md`
- Compatibility: `COMPATIBILITY.md`
- Local live demo: `LIVE_DEMO.md`
- Agent input contract: `AGENT_INPUT_CONTRACT.md`

## Maintainer

- **Zipeng Wu**
- The University of Birmingham
- zxw365@student.bham.ac.uk
- https://github.com/ZipengWu365/EchoWave
