sequenzo 0.1.21__cp311-cp311-macosx_11_0_arm64.whl

sequenzo/with_event_history_analysis/sequence_history_analysis.py

@@ -0,0 +1,283 @@
+"""
+@Author  : Yuqi Liang 梁彧祺
+@File    : sequence_history_analysis.py
+@Time    : 30/09/2025 21:08
+@Desc    : Sequence History Analysis - Convert person-level sequence data to person-period format
+"""
+
+import numpy as np
+import pandas as pd
+
+
+def person_level_to_person_period(data, id_col="id", period_col="time", event_col="event"):
+    """
+    Convert person-level data to person-period format.
+    
+    This function expands each person's single row into multiple rows,
+    one for each time period they are observed.
+    
+    Parameters
+    ----------
+    data : pandas.DataFrame
+        Input data with one row per person
+    id_col : str, optional
+        Name of the ID column (default: "id")
+    period_col : str, optional
+        Name of the time period column (default: "time")
+    event_col : str, optional
+        Name of the event indicator column (default: "event")
+    
+    Returns
+    -------
+    pandas.DataFrame
+        Expanded data with one row per person-period
+    
+    Examples
+    --------
+    >>> data = pd.DataFrame({'id': [1, 2], 'time': [3, 2], 'event': [True, False]})
+    >>> person_level_to_person_period(data)
+       id  time  event
+    0   1     1  False
+    1   1     2  False
+    2   1     3   True
+    3   2     1  False
+    4   2     2  False
+    """
+    # Check for missing values in critical columns
+    if data[[id_col, period_col, event_col]].isna().any().any():
+        raise ValueError("Cannot handle missing data in the time or event variables")
+    
+    # Create an index that repeats each row based on the time value
+    # For example, if time=3, that row will be repeated 3 times
+    index = np.repeat(np.arange(len(data)), data[period_col].values)
+    
+    # Find the cumulative sum to identify which rows should have the event
+    idmax = np.cumsum(data[period_col].values) - 1
+    
+    # Expand the data by repeating rows
+    dat = data.iloc[index].copy()
+    dat.reset_index(drop=True, inplace=True)
+    
+    # Create sequential time periods for each ID (1, 2, 3, ...)
+    dat[period_col] = dat.groupby(id_col).cumcount() + 1
+    
+    # Set all events to False initially
+    dat[event_col] = False
+    
+    # Set events to True only at the final period for each person
+    # Convert to bool to avoid dtype incompatibility warning
+    dat.loc[idmax, event_col] = data[event_col].values.astype(bool)
+    
+    return dat
+
+
+def _extract_sequence_dataframe(seqdata):
+    """
+    Extract sequence DataFrame from various input types.
+    
+    Parameters
+    ----------
+    seqdata : SequenceData, pandas.DataFrame, or numpy.ndarray
+        Input sequence data
+    
+    Returns
+    -------
+    pandas.DataFrame
+        Sequence data as a DataFrame
+    """
+    # Check if input is a SequenceData object
+    if hasattr(seqdata, 'seqdata'):
+        # This is a SequenceData object
+        return seqdata.seqdata.copy()
+    elif isinstance(seqdata, pd.DataFrame):
+        return seqdata.copy()
+    else:
+        # Assume it's array-like
+        return pd.DataFrame(seqdata)
+
+
+def seqsha(seqdata, time, event, include_present=False, align_end=False, covar=None):
+    """
+    Sequence History Analysis: Create person-period format with sequence history.
+    
+    This function converts sequence data into a person-period format where each
+    row represents a time point for a person, with columns showing their sequence
+    history up to that point.
+    
+    Parameters
+    ----------
+    seqdata : SequenceData, pandas.DataFrame, or numpy.ndarray
+        Sequence data where each row is a person and each column is a time point.
+        Can be a SequenceData object, DataFrame, or array.
+    time : array-like
+        Duration or time until event for each person. Length should equal the 
+        number of sequences. Each value indicates how many time periods that 
+        person is observed. For example, if all persons are observed for the 
+        full sequence length, use: np.full(n_persons, sequence_length)
+    event : array-like
+        Event indicator for each person (True/False or 1/0). Length should 
+        equal the number of sequences.
+    include_present : bool, optional
+        If True, include the current time point in the history (default: False)
+        If False, only include past time points (recommended for most analyses)
+    align_end : bool, optional
+        If True, align sequences from the end (right-aligned) (default: False)
+        If False, align sequences from the start (left-aligned)
+    covar : pandas.DataFrame or numpy.ndarray, optional
+        Additional covariates to merge with the output (default: None)
+        Should have the same number of rows as seqdata
+    
+    Returns
+    -------
+    pandas.DataFrame
+        Person-period data with the following columns:
+        - id: Person identifier
+        - time: Time period within person
+        - event: Event indicator (True only at the final period for each person)
+        - Sequence history columns (varies based on align_end parameter)
+        - Additional covariate columns (if covar is provided)
+    
+    Raises
+    ------
+    ValueError
+        If maximum time exceeds the length of the longest sequence
+    
+    Examples
+    --------
+    Example 1: Basic usage with DataFrame
+    >>> import pandas as pd
+    >>> import numpy as np
+    >>> seqdata = pd.DataFrame([[1, 2, 3, 4], [1, 1, 2, 2]])
+    >>> time = np.array([3, 2])
+    >>> event = np.array([True, False])
+    >>> result = seqsha(seqdata, time, event)
+    
+    Example 2: Usage with SequenceData object (recommended)
+    >>> from sequenzo import SequenceData, load_dataset
+    >>> df = load_dataset('pairfam_family')
+    >>> time_cols = [str(i) for i in range(1, 265)]
+    >>> seq_data = SequenceData(df, time=time_cols, id_col='id', 
+    ...                          states=list(range(1, 10)))
+    >>> # All persons observed for 264 months
+    >>> time = np.full(len(df), 264)
+    >>> event = df['highschool'].values
+    >>> result = seqsha(seq_data, time, event)
+    
+    Example 3: With covariates
+    >>> covar = df[['sex', 'yeduc', 'east']]
+    >>> result = seqsha(seq_data, time, event, covar=covar)
+    
+    Example 4: Right-aligned sequences
+    >>> result = seqsha(seq_data, time, event, align_end=True)
+    
+    Notes
+    -----
+    - The time parameter represents observation duration, not calendar time
+    - When include_present=False (default), only past states are included
+    - Use align_end=True when analyzing sequences leading up to an event
+    - Missing values in the original sequence are converted to "NA_orig"
+    """
+    # Extract sequence DataFrame from input (handles SequenceData, DataFrame, or array)
+    seq_df = _extract_sequence_dataframe(seqdata)
+    
+    # Convert time and event to numpy arrays for consistency
+    time_array = np.asarray(time)
+    event_array = np.asarray(event)
+    
+    # Check that dimensions match
+    n_sequences = len(seq_df)
+    if len(time_array) != n_sequences:
+        raise ValueError(
+            f"Length of 'time' ({len(time_array)}) must match number of sequences ({n_sequences})"
+        )
+    if len(event_array) != n_sequences:
+        raise ValueError(
+            f"Length of 'event' ({len(event_array)}) must match number of sequences ({n_sequences})"
+        )
+    
+    # Create base time data: one row per person with their time and event
+    basetime = pd.DataFrame({
+        'id': np.arange(1, n_sequences + 1),
+        'time': time_array,
+        'event': event_array
+    })
+    
+    # Convert to person-period format (expand rows)
+    persper = person_level_to_person_period(basetime, "id", "time", "event")
+    
+    # Convert sequence data to matrix and handle missing values
+    sdata = seq_df.values.astype(str)
+    sdata[pd.isna(seq_df.values)] = "NA_orig"
+    
+    # Get the time periods for each row in person-period data
+    age = persper['time'].values
+    ma = int(np.max(age))
+    
+    # Check if time values are valid
+    if ma > seq_df.shape[1]:
+        raise ValueError("Maximum time of event occurrence is higher than the longest sequence!")
+    
+    # Create empty matrix to store past sequence states
+    past = np.full((len(persper), seq_df.shape[1]), np.nan, dtype=object)
+    
+    if align_end:
+        # Right-align the sequences (align from the end)
+        start = 1 if include_present else 2
+        
+        for aa in range(start, ma + 1):
+            # Find rows where time equals aa
+            cond = age == aa
+            # Get the person IDs for these rows
+            ids_a = persper.loc[cond, 'id'].values - 1  # Subtract 1 for 0-based indexing
+            
+            if include_present:
+                # Include current time point: fill from (ncol-aa) to end
+                past[cond, (seq_df.shape[1] - aa):seq_df.shape[1]] = sdata[ids_a, 0:aa]
+            else:
+                # Exclude current time point: fill from (ncol-aa+1) to end
+                past[cond, (seq_df.shape[1] - aa + 1):seq_df.shape[1]] = sdata[ids_a, 0:(aa - 1)]
+        
+        # Create column names counting backwards
+        col_names = [f"Tm{i}" for i in range(seq_df.shape[1], 0, -1)]
+    else:
+        # Left-align the sequences (align from the start)
+        for aa in range(1, ma + 1):
+            if include_present:
+                # Include present: use time > aa
+                cond = age > aa
+            else:
+                # Exclude present: use time >= aa
+                cond = age >= aa
+            
+            # Get the person IDs for these rows
+            ids_a = persper.loc[cond, 'id'].values - 1  # Subtract 1 for 0-based indexing
+            
+            # Fill in the sequence state at position aa-1 (0-based)
+            past[cond, aa - 1] = sdata[ids_a, aa - 1]
+        
+        # Use original column names or create default ones
+        if seq_df.columns is not None and len(seq_df.columns) > 0:
+            col_names = [str(col) for col in seq_df.columns[:ma]]
+            # Pad with additional column names if needed
+            col_names += [f"col_{i}" for i in range(ma, seq_df.shape[1])]
+        else:
+            col_names = [f"col_{i}" for i in range(seq_df.shape[1])]
+    
+    # Convert past matrix to DataFrame
+    past_df = pd.DataFrame(past, columns=col_names)
+    
+    # Combine person-period data with sequence history
+    alldata = pd.concat([persper.reset_index(drop=True), past_df], axis=1)
+    
+    # Add covariates if provided
+    if covar is not None:
+        # Merge covariates based on the ID (subtract 1 for 0-based indexing)
+        if isinstance(covar, pd.DataFrame):
+            covar_subset = covar.iloc[alldata['id'].values - 1].reset_index(drop=True)
+            alldata = pd.concat([alldata, covar_subset], axis=1)
+        else:
+            covar_array = np.array(covar)
+            covar_subset = covar_array[alldata['id'].values - 1]
+            alldata = pd.concat([alldata, pd.DataFrame(covar_subset)], axis=1)
+    
+    return alldata

sequenzo-0.1.21.dist-info/METADATA

@@ -0,0 +1,308 @@
+Metadata-Version: 2.4
+Name: sequenzo
+Version: 0.1.21
+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>=2.0.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.6.3
+Requires-Dist: scikit-learn>=0.24.2
+Requires-Dist: fastcluster>=1.2.6
+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
+Provides-Extra: r
+Requires-Dist: rpy2>=3.5.12; python_version >= "3.12" and extra == "r"
+Requires-Dist: rpy2>=3.5.6; python_version == "3.11" and extra == "r"
+Requires-Dist: rpy2>=3.5.6; python_version == "3.10" and extra == "r"
+Requires-Dist: rpy2>=3.5.6; python_version == "3.9" and extra == "r"
+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. It 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.
+
+## ✨ 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/3bMDKRHW
+
+## 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**        | `universal2` (Intel + Apple Silicon) | 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?
+- **universal2 (macOS)**: One wheel supports both Intel (x86_64) and Apple Silicon (arm64) Macs.
+- **manylinux2014 (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
+```
+
+### ⚠️ Having Installation or Import Issues?
+
+**Error:** `ImportError: numpy.core.multiarray failed to import` or `ValueError: numpy.dtype size changed`
+
+**Cause:** NumPy version incompatibility. Sequenzo 0.1.21+ requires NumPy 2.x.
+
+**Quick Fix** (copy-paste these commands):
+```bash
+# Check your NumPy version first
+python -c "import numpy; print(f'NumPy: {numpy.__version__}')"
+
+# If you see 1.x.x, upgrade to 2.x:
+pip install --upgrade "numpy>=2.0.0"
+pip uninstall sequenzo -y
+pip install --no-cache-dir sequenzo
+```
+
+**Note:** NumPy 2.x is backward compatible with code written for NumPy 1.x, so upgrading is safe.
+
+📖 **Still having issues?** 
+1. Run our diagnostic tool to identify the problem:
+   ```bash
+   curl -O https://raw.githubusercontent.com/Liang-Team/Sequenzo/main/diagnose.py
+   python diagnose.py
+   ```
+2. See our detailed guides:
+   - **[QUICK_FIX.md](QUICK_FIX.md)** - Simple step-by-step solutions
+   - **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Comprehensive troubleshooting
+   - **[docs/WHY_IMPORT_FAILS.md](docs/WHY_IMPORT_FAILS.md)** - Technical explanation
+
+### Optional R Integration
+
+Sequenzo now checks the system environment variables before running ward.D hierarchical clustering.
+
+If R is missing, a relevant prompt will be displayed along with specific installation instructions. If `fastcluster` is missing, Sequenzo will automatically download `fastcluster`.
+
+Before automatically downloading `fastcluster`, Sequenzo checks whether R is available; if R is not installed, sequenzo will not automatically download fastcluster.
+
+Sequenzo supports advanced Ward clustering methods that require R integration. If you need to use the `ward_d` clustering method, install with R support:
+
+```
+pip install sequenzo[r]
+```
+
+This will install the optional `rpy2` dependency, which provides Python-R interoperability. Note that R must also be installed on your system for `rpy2` to work.
+
+For more information about the latest stable release and required dependencies, please refer to [PyPI](https://pypi.org/project/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.inet.ox.ac.uk/people/jan-meyerhoff-liang)
+
+**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**
+
+* Methodological advisor in sequence analysis: [Professor Tim Liao (University of Illinois Urbana-Champaign)](https://sociology.illinois.edu/directory/profile/tfliao)
+* 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)
+