yasqat 0.5.0

Yet Another Sequence Analytics Toolkit - A modern Python library for sequence analysis with polars

yasqat

Yet Another Sequence Analytics Toolkit

A modern Python library for categorical sequence analysis, built on polars. Designed for social-science and life-course research — labour-market trajectories, health pathways, educational histories, and similar domains.

Inspired by TraMineR (R) and 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

pip install yasqat

Quick start

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

# 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 setup:

• Issues are tracked in-repo as markdown under .scratch/ (single source of truth) — see .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 for details.

Acknowledgments

• Inspired by TraMineR (R) and TanaT (Python)
• Built with polars, numba, and scipy