Metadata-Version: 2.4
Name: yasqat
Version: 0.5.0
Summary: Yet Another Sequence Analytics Toolkit - A modern Python library for sequence analysis with polars
Project-URL: Homepage, https://github.com/rexarski/yasqat
Project-URL: Repository, https://github.com/rexarski/yasqat
Project-URL: Issues, https://github.com/rexarski/yasqat/issues
Author-email: rexarski <rexarski@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: event-sequences,polars,sequence-analysis,state-sequences,temporal-data,trajectory-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: numba>=0.60
Requires-Dist: numpy>=1.26
Requires-Dist: polars>=1.0
Requires-Dist: pyarrow>=15.0
Requires-Dist: scipy>=1.11
Provides-Extra: dev
Requires-Dist: mypy>=1.14; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo>=2024.8.6; extra == 'docs'
Requires-Dist: myst-parser>=4.0; extra == 'docs'
Requires-Dist: sphinx>=8.1; extra == 'docs'
Description-Content-Type: text/markdown

# yasqat

**Yet Another Sequence Analytics Toolkit**

[![PyPI](https://img.shields.io/pypi/v/yasqat)](https://pypi.org/project/yasqat/)
[![Python](https://img.shields.io/pypi/pyversions/yasqat)](https://pypi.org/project/yasqat/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

A modern Python library for categorical sequence analysis, built on
[polars](https://pola.rs/). Designed for social-science and life-course
research — labour-market trajectories, health pathways, educational
histories, and similar domains.

Inspired by [TraMineR](http://traminer.unige.ch/) (R) and
[TanaT](https://tanat.gitlabpages.inria.fr/core/tanat/) (Python).

## Features

- **Polars-native data structures** — `Alphabet`, `StateSequence`,
  `SequencePool` for fast sequence manipulation. Interval-shaped input is
  sampled into a `StateSequence` via `StateSequence.from_intervals(df, time_points=...)`.
- **Distance metrics** — Optimal Matching, Hamming, LCS, LCP, RLCP, DTW,
  SoftDTW, Chi², Euclidean, DHD, TWED, and OM variants (OMloc, OMspell,
  OMstran, NMS, NMSMST, SVRspell), with convenience length/similarity
  wrappers for LCS, LCP, and RLCP
- **Substitution costs** — constant, transition-rate, indels, indelslog,
  future (chi-squared), features (Gower distance)
- **Clustering** — PAM (k-medoids) with `.predict()`, CLARA, hierarchical
  (scipy linkage); parallel pairwise distance computation via `n_jobs`
- **Cluster quality** — silhouette (ASW), Point Biserial, Hubert's Gamma,
  R², PAM range analysis, distance to center, representative extraction
- **Discrepancy analysis** — pseudo-ANOVA with permutation tests,
  multi-factor discrepancy, dissimilarity trees
- **Descriptive statistics** — entropy, transition rates, complexity,
  turbulence, spell counts, visited states, modal states (with time
  granularity), sequence frequencies, log-probabilities, subsequence
  counts (with state filtering and log-transform), per-sequence state
  distributions
- **Normative indicators** — volatility, objective (label-free) volatility,
  precarity, insecurity, degradation, badness, integration (per-state),
  proportion positive
- **Subsequence mining** — frequent subsequence discovery with support
  thresholds and minimum length, plus sequential association rules
  (confidence, lift, leverage, conviction), returned as polars DataFrames
- **Plot-library agnostic** — every method returns a polars `DataFrame`,
  so users can plot with their tool of choice (matplotlib, altair,
  observable, …). `Alphabet.colors` is exposed for consistent palette use.
- **Filtering** — length, time, state, and starts-with sequence filtering
- **Data I/O** — CSV, Parquet, and DataFrame loading (Hive/Spark/Arrow
  interop) with automatic type inference
- **Synthetic data** — Markov-chain and financial trajectory generators

## Installation

```bash
pip install yasqat
```

## Quick start

```python
from yasqat.io import load_csv

# Load sequences from CSV (also: load_dataframe, load_json, load_parquet).
# Every loader returns a SequencePool, the analysis container. Default column
# names are id/time/state; pass config=SequenceConfig(...) to override.
pool = load_csv("trajectories.csv")

# Compute pairwise distances and cluster
dm = pool.compute_distances(method="om", indel=1.0, n_jobs=4)

from yasqat.clustering import pam_clustering
result = pam_clustering(dm, n_clusters=4)

# Descriptive statistics
from yasqat.statistics import longitudinal_entropy, turbulence
longitudinal_entropy(pool)
turbulence(pool)

# Plot with your library of choice — yasqat methods return polars DataFrames
state_distribution = pool.to_state_sequence().state_per_sequence(proportion=True)
# Hand `state_distribution` to matplotlib, altair, etc.
```

## Development

```bash
# Clone and install with dev dependencies
git clone https://github.com/rexarski/yasqat.git
cd yasqat
uv venv && source .venv/bin/activate  # or activate.fish
uv pip install -e ".[dev]"

# Run tests
uv run pytest

# Lint and format
uv run ruff check src/ tests/
uv run ruff format src/ tests/

# Type check
uv run mypy src/yasqat/
```

### Project conventions

Development guidance lives in `CLAUDE.md`. This repo follows
[Matt Pocock's agent-skills](https://github.com/mattpocock/skills) setup:

- **Issues** are tracked in-repo as markdown under `.scratch/` (single source
  of truth) — see [`.scratch/README.md`](.scratch/README.md) for the board.
- **Agent configuration** (issue tracker, triage labels, domain docs) lives in
  `docs/agents/`.
- **Architecture decisions** are recorded as ADRs in `docs/adr/`.

## License

MIT License — see [LICENSE](LICENSE) for details.

## Acknowledgments

- Inspired by [TraMineR](http://traminer.unige.ch/) (R) and
  [TanaT](https://gitlab.inria.fr/tanat/core/tanat) (Python)
- Built with [polars](https://pola.rs/),
  [numba](https://numba.pydata.org/), and [scipy](https://scipy.org/)
