Metadata-Version: 2.4
Name: sequenzo
Version: 0.1.34
Summary: A fast, scalable and intuitive Python package for social sequence analysis.
Author-email: Yuqi Liang <yuqi.liang.1900@gmail.com>, Xinyi Li <1836724126@qq.com>, Jan Heinrich Ernst Meyerhoff-Liang <jan.meyerhoff1@gmail.com>
License: BSD 3-Clause License
        
        Copyright (c) 2025, Yuqi Liang
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Project-URL: Homepage, https://github.com/Liang-Team/Sequenzo
Project-URL: Documentation, https://sequenzo.yuqi-liang.tech
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: <3.13,>=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: pandas>=1.2.5
Requires-Dist: matplotlib>=3.4.3
Requires-Dist: seaborn>=0.11.2
Requires-Dist: Pillow>=8.3.2
Requires-Dist: pybind11>=2.6.0
Requires-Dist: cython>=0.29.21
Requires-Dist: scipy<1.17,>=1.6.3
Requires-Dist: scikit-learn>=0.24.2
Requires-Dist: joblib>=1.0.1
Requires-Dist: docutils>=0.17
Requires-Dist: tqdm<5.0.0,>=4.62.3
Requires-Dist: missingno<0.6.0,>=0.5.2
Requires-Dist: cffi>=1.15.0
Requires-Dist: hmmlearn>=0.2.0
Provides-Extra: dev
Requires-Dist: pytest>=6.2.5; extra == "dev"
Requires-Dist: flake8>=3.9.2; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/Liang-Team/Sequenzo/main/assets/logo/FullLogo_NoBuffer.jpg" alt="Sequenzo Logo" width="300">
</p>

<p align="center">
  <!-- ✅ PyPI Latest Version Badge -->
  <a href="https://pypi.org/project/sequenzo/">
    <img alt="PyPI - Version" src="https://img.shields.io/pypi/v/sequenzo?color=blue">
  </a>

  <!-- 📦 Downloads Badge (可选) -->
  <a href="https://pypi.org/project/sequenzo/">
    <img alt="Downloads" src="https://static.pepy.tech/badge/sequenzo">
  </a>

  <!-- 📄 License Badge -->
  <a href="https://github.com/Liang-Team/Sequenzo/blob/main/LICENSE">
    <img alt="License" src="https://img.shields.io/github/license/Liang-Team/Sequenzo">
  </a>
</p>

# Sequenzo: Fast, scalable, and intuitive social sequence analysis in Python

Sequenzo is a high-performance Python package designed for social sequence analysis. 

Its methodological foundations build upon prior work in the R ecosystem, especially
[the TraMineR (Gabadinho et al. 2011) R package](https://traminer.unige.ch/), which
established many of the core concepts, representations, and analytical tools in
sequence analysis, as well as subsequent methodological extensions developed within
[TraMineRextras (Gabadinho et al. 2021)](https://cran.r-project.org/web/packages/TraMineRextras/index.html).

Sequenzo also draws inspiration from
[WeightedCluster (Studer, 2013)](https://mephisto.unige.ch/weightedcluster/) for
typology construction,
[seqHMM (Helske & Helske, 2019)](https://www.jstatsoft.org/article/view/v088i03) for
probabilistic modeling using hidden Markov models,
and [ggseqplot (Raab, 2022)](https://maraab23.github.io/ggseqplot/) for the design of
relative frequency sequence visualizations (Fasang & Liao, 2013).

We gratefully acknowledge these pioneering contributions and the broader community in social sequence analysis whose work enables everything we do. Sequenzo seeks to expand the social sequence analysis ecosystem by connecting long-standing methodological traditions with the computational practices of the Python data science community, particularly in machine learning and deep learning.

---

Sequenzo is built to analyze **any sequence of categorical events**, from individual career paths and migration patterns to corporate growth and urban development. 
Whether you are working with **people, places, or policies**, Sequenzo helps uncover meaningful patterns efficiently. 

Sequenzo outperforms traditional R-based tools in social sequence analysis, delivering faster processing and superior efficiency, especially for large-scale datasets. **No big data? No problem. You don’t need big data to benefit as Sequenzo is designed to enhance sequence analysis at any scale, making complex methods accessible to everyone.**

> 🚀 **Explore the official documentation at [sequenzo.yuqi-liang.tech](https://sequenzo.yuqi-liang.tech/en/)**  
> with tutorials, practical examples, and API references to help you get started quickly.  
>  
> 📖 Available in **English and Chinese**, our docs are written to be approachable, practical, and easy to follow.
>
> ✍️ Regarding **how to cite us**, please see [here](https://sequenzo.yuqi-liang.tech/en/basics/how-to-cite).  

## ✨ Be part of the Sequenzo community
Join our Discord channel to iscuss ideas, get help, and hear about upcoming Sequenzo versions, tutorials, and workshops first.

➡️ https://discord.gg/RHfDuu4ETz

## Target Users

Sequenzo is designed for:

- Quantitative researchers in sociology, demography, political science, economics, management, etc.
- Data scientists, data analysts, and business analysts working on trajectory/time-series clustering
- Educators teaching courses involving social sequence data
- Users familiar with R packages such as `TraMineR` who want a Python-native alternative

## Why Choose Sequenzo?

🚀 **High Performance**

Leverages Python’s computational power to achieve 8× faster processing than traditional R-based tools like TraMineR.

🎯 **Easy-to-Use API**

Designed with simplicity in mind: intuitive functions streamline complex sequence analysis without compromising flexibility.

🌍 **Flexible for Any Scenario**

Perfect for research, policy, and business, enabling seamless analysis of categorical data and its evolution over time.

## Platform Compatibility

Sequenzo provides pre-built Python wheels for maximum compatibility — no need to compile from source.

| Platform         | Architecture                   | Python Versions       | Status            |
|------------------|--------------------------------|-----------------------|-------------------|
| **macOS**        | Intel && Apple Silicon (64-bit) | 3.9, 3.10, 3.11, 3.12 | ✅ Pre-built wheel |
| **Windows**      | `AMD64`(64-bit)     | 3.9, 3.10, 3.11, 3.12 | ✅ Pre-built wheel |
| **Linux (glibc)**| `x86_64` (standard Linux)      | 3.9, 3.10, 3.11, 3.12 | ✅ Pre-built wheel |
| **Linux (musl)** | `x86_64` (Alpine Linux)        | 3.9, 3.10, 3.11, 3.12 | ✅ Pre-built wheel |


What do these terms mean?
- **macosx_arm64 (macOS)**: One wheel supports Apple Silicon Macs.
- **macosx_x86_64 (macOS)**: One wheel supports Intel Macs.
- **manylinux2014_x86_64 (glibc-based Linux)**: Compatible with most mainstream Linux distributions (e.g., Ubuntu, Debian, CentOS).
- **musllinux_1_2 (musl-based Linux)**: For lightweight Alpine Linux environments, common in Docker containers.
- **AMD64 (Windows)**: Standard 64-bit Windows system architecture.

All of these wheels are pre-built and available on PyPI — so `pip install sequenzo` should work on supported platforms, without needing a compiler.

**Windows (win32)** and **Linux (i686)** are dropped due to:

- Extremely low usage in modern systems (post-2020)
- Memory limitations (≤ 4GB) unsuitable for scientific computing workloads
- Increasing incompatibility with packages such as `numpy`, `scipy`, and `pybind11`
- Frequent build failures and maintenance overhead in CI/CD pipelines


## Installation

If you haven't installed Python, please follow [Yuqi's tutorial about how to set up Python and your virtual environment](https://www.yuqi-liang.tech/blog/setup-python-virtual-environment/). 

Once Python is installed, we highly recommend using [PyCharm](https://www.jetbrains.com/pycharm/download/) as your IDE (Integrated Development Environment — the place where you open your folder and files to work with Python), rather than Visual Studio. PyCharm has excellent built-in support for managing virtual environments, making your workflow much easier and more reliable.

In PyCharm, please make sure to select a virtual environment using Python 3.9, 3.10, or 3.11 as these versions are fully supported by `sequenzo`.

Then, you can open the built-in terminal by clicking the Terminal icon 
<img src="https://github.com/user-attachments/assets/1e9e3af0-4286-47ba-aa88-29c3288cb7cb" alt="terminal icon" width="30" style="display:inline; vertical-align:middle;"> 
in the left sidebar (usually near the bottom). It looks like a small command-line window icon.

Once it’s open, type the following to install `sequenzo`:

```
pip install sequenzo
```

If you have some issues with the installation, it might because you have both Python 2 and Python 3 installed on your computer. In this case, you can try to use `pip3` instead of `pip` to install the package.

```
pip3 install sequenzo
```

## Documentation

Explore the full Sequenzo documentation [here](sequenzo.yuqi-liang.tech). Even though the documentation website is still under construction, you can already find some useful information there.

**Where to start on the documentation website?**
* New to Sequenzo or social sequence analysis? Begin with "About Sequenzo" → "Quickstart Guide" for a smooth introduction.
* Got your own data? After going through "About Sequenzo" and "Quickstart Guide", you are ready to dive in and start analyzing.
* Looking for more? Check out our example datasets and tutorials to deepen your understanding.

For Chinese users, additional tutorials are available on [Yuqi's video tutorials on Bilibili](https://space.bilibili.com/263594713/lists/4147974).

## Join the Community

💬 **Have a question or found a bug?**

Please submit an issue on [GitHub Issues](https://github.com/Liang-Team/Sequenzo/issues) by following [this instruction](https://sequenzo.yuqi-liang.tech/en/faq/bug_reports_and_feature_requests).

* We will respond as quickly as possible.
* For requests that are not too large, we aim to fix or implement the feature **within one week** from our response time.
* Timeline may vary depending on how many requests we receive.

🌟 **Enjoying Sequenzo?**

Support the project by starring ⭐ the GitHub repo and spreading the word!

🛠 **Interested in contributing?**

Check out our [contribution guide]() for more details (work in progress). 

* Write code? Submit a pull request to enhance Sequenzo.
* Testing? Try Sequenzo and share your feedback. Every suggestion counts!

If you're contributing or debugging, use:

```bash
pip install -r requirements/requirements-3.10.txt  # Or matching your Python version
```
    
For standard installation, use:

```bash
pip install .  # Uses pyproject.toml
```

## Team

**Paper Authors**
* [Yuqi Liang, University of Oxford](https://www.yuqi-liang.tech/)
* [Xinyi Li, Northeastern University](https://github.com/Fantasy201)
* [Jan Heinrich Ernst Meyerhoff-Liang, Institute for New Economic Thinking Oxford](https://www.linkedin.com/in/jan-meyerhoff-liang-97999a170/)

**Package Contributors**

Coding contributors:
* [Sebastian Daza](https://sdaza.com/)
* [Cheng Deng](https://github.com/de-de-de-de-de)
* [Liangxingyun He, Stockholm School of Economics, Sweden](https://www.linkedin.com/in/liangxingyun-he-6aa128304/)

Documentation contributors:
* [Liangxingyun He, Stockholm School of Economics, Sweden](https://www.linkedin.com/in/liangxingyun-he-6aa128304/)
* [Yukun Ming, Universidad Carlos III de Madrid (Spain)](https://www.linkedin.com/in/yukun)
* [Sizhu Qu, Northeastern University (US)](https://www.linkedin.com/in/sizhuq)
* [Ziting Yang, Rochester Wniversity (US)](https://www.linkedin.com/in/ziting-yang-7b33832bb)

Others
* With special thanks to our initial testers (alphabetically ordered): [Joji Chia](https://sociology.illinois.edu/directory/profile/jbchia2), [Kass Gonzalez](https://www.linkedin.com/in/kass-gonzalez-72a778276/), [Sinyee Lu](https://sociology.illinois.edu/directory/profile/qianyil4), [Sohee Shin](https://sociology.illinois.edu/directory/profile/sohees2)
* Website and related technical support: [Mactavish](https://github.com/mactavishz)
* Sequence data sources compilation - History: Jingrui Chen
* Visual design consultant: Changyu Yi

**Acknowledgements**

* Amazing authors of R packages in soial sequence analysis, including [TraMineR (Gabadinho et al. 2011)](https://traminer.unige.ch/), [WeightedCluster (Studer, 2013)](https://mephisto.unige.ch/weightedcluster/), and [seqHMM (Helske & Helske, 2019)](https://cran.r-project.org/web/packages/seqHMM/index.html)
* Methodological advisor in sequence analysis: [Professor Tim Liao (University of Illinois Urbana-Champaign)](https://sociology.illinois.edu/directory/profile/tfliao)
* [Social Sequence Analysis Association](https://sequenceanalysis.org/)
* Helpful discussions and comments: 
  * [Gilbert Ritschard](https://mephisto.unige.ch/Gilbert/)
  * [Matthias Studer](https://www.unige.ch/sciences-societe/ideso/membres/matthias-studer)
  * [Emanuela Struffolino](https://emastruffolino.github.io/)
  * [Marcel Raab](https://marcelraab.de/)
  * [Heyi Zhang](https://profiles.ucl.ac.uk/100967-heyi-zhang)
* Yuqi's PhD advisor [Professor Ridhi Kashyap (University of Oxford)](https://www.nuffield.ox.ac.uk/people/profiles/ridhi-kashyap/), and mentor [Charles Rahal (University of Oxford)](https://crahal.com/)
* Yuqi's original programming mentor: [JiangHuShiNian](https://github.com/jianghushinian)

