sequenzo 0.1.31__cp310-cp310-macosx_10_9_x86_64.whl

sequenzo/version_check.py

@@ -0,0 +1,283 @@
+"""
+@Author  : Yuqi Liang 梁彧祺
+@File    : version_check.py
+@Time    : 2025-11-20 07:27
+@Desc    : Version check utility for Sequenzo
+
+This module checks if the installed version of Sequenzo is up-to-date
+by comparing it with the latest version available on PyPI.
+Similar to pip's version notice functionality.
+"""
+
+import sys
+import warnings
+from typing import Optional, Tuple
+
+# Try to import packaging for version comparison, fallback to simple comparison
+try:
+    from packaging import version as packaging_version
+    HAS_PACKAGING = True
+except ImportError:
+    HAS_PACKAGING = False
+
+
+def get_installed_version() -> str:
+    """
+    Get the currently installed version of Sequenzo.
+    
+    This function tries multiple methods to get the version:
+    1. First, try to get version from the currently imported sequenzo module
+       (works in development mode when project directory is in sys.path)
+    2. Then, try importlib.metadata (works for installed packages)
+    3. Finally, try reading from pyproject.toml (fallback for development)
+    
+    Returns:
+        str: The installed version string (e.g., "0.1.24")
+    """
+    # Method 1: Try to get version from currently imported sequenzo module
+    # This works in development mode when the project directory is in sys.path
+    try:
+        import sequenzo
+        if hasattr(sequenzo, '__version__'):
+            version = sequenzo.__version__
+            # Clean up version string (remove any git commands accidentally included)
+            version = version.split()[0] if version else None
+            if version:
+                return version
+    except (ImportError, AttributeError):
+        pass
+    
+    # Method 2: Try to get version from importlib.metadata (for installed packages)
+    try:
+        if sys.version_info >= (3, 8):
+            from importlib.metadata import version as get_package_version
+            return get_package_version("sequenzo")
+        else:
+            # Fallback for Python < 3.8
+            import pkg_resources
+            return pkg_resources.get_distribution("sequenzo").version
+    except Exception:
+        pass
+    
+    # Method 3: Try to read from pyproject.toml (fallback for development mode)
+    # Use simple regex parsing to avoid dependency on tomli/tomllib
+    try:
+        import os
+        import re
+        
+        # Find project root (where pyproject.toml should be)
+        current_dir = os.path.dirname(os.path.abspath(__file__))
+        project_root = os.path.dirname(os.path.dirname(current_dir))
+        pyproject_path = os.path.join(project_root, "pyproject.toml")
+        
+        if os.path.exists(pyproject_path):
+            with open(pyproject_path, "r", encoding="utf-8") as f:
+                content = f.read()
+                # Simple regex to find version = "x.y.z" in [project] section
+                # Look for pattern: version = "0.1.30" or version = '0.1.30'
+                match = re.search(r'^\s*version\s*=\s*["\']([^"\']+)["\']', content, re.MULTILINE)
+                if match:
+                    return match.group(1)
+    except Exception:
+        pass
+    
+    # If all methods fail, return None
+    return None
+
+
+def get_latest_version_from_pypi(package_name: str = "sequenzo", timeout: float = 1.0) -> Optional[str]:
+    """
+    Check PyPI for the latest version of the package.
+    
+    This function queries the PyPI JSON API to get the latest version.
+    It uses a timeout to avoid blocking if the network is slow or unavailable.
+    
+    Args:
+        package_name: Name of the package on PyPI (default: "sequenzo")
+        timeout: Timeout in seconds for the HTTP request (default: 1.0)
+        
+    Returns:
+        Optional[str]: The latest version string if available, None otherwise
+    """
+    try:
+        import urllib.request
+        import json
+        
+        # PyPI JSON API endpoint
+        url = f"https://pypi.org/pypi/{package_name}/json"
+        
+        # Create request with timeout
+        request = urllib.request.Request(url)
+        request.add_header("User-Agent", f"sequenzo/{get_installed_version() or 'unknown'}")
+        
+        # Make request with timeout
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            data = json.loads(response.read().decode())
+            return data.get("info", {}).get("version")
+    except Exception:
+        # Silently fail if we can't check (network issues, etc.)
+        return None
+
+
+def _simple_version_compare(installed: str, latest: str) -> bool:
+    """
+    Simple version comparison without external dependencies.
+    
+    This function compares version strings by splitting on '.' and comparing
+    each component numerically. This works for most standard version formats
+    like "0.1.24" but may not handle all edge cases.
+    
+    Args:
+        installed: Currently installed version
+        latest: Latest available version
+        
+    Returns:
+        bool: True if installed >= latest, False otherwise
+    """
+    try:
+        # Split versions into components
+        installed_parts = [int(x) for x in installed.split('.')]
+        latest_parts = [int(x) for x in latest.split('.')]
+        
+        # Pad shorter version with zeros
+        max_len = max(len(installed_parts), len(latest_parts))
+        installed_parts.extend([0] * (max_len - len(installed_parts)))
+        latest_parts.extend([0] * (max_len - len(latest_parts)))
+        
+        # Compare component by component
+        for i, l in zip(installed_parts, latest_parts):
+            if i > l:
+                return True  # installed is newer
+            elif i < l:
+                return False  # installed is older
+        
+        return True  # versions are equal
+    except (ValueError, AttributeError):
+        # If parsing fails, do string comparison as fallback
+        return installed >= latest
+
+
+def compare_versions(installed: str, latest: str) -> Tuple[bool, str]:
+    """
+    Compare two version strings to determine if an update is available.
+    
+    Args:
+        installed: Currently installed version
+        latest: Latest available version
+        
+    Returns:
+        Tuple[bool, str]: (is_up_to_date, message)
+            - is_up_to_date: True if installed version >= latest version
+            - message: Human-readable comparison message
+    """
+    try:
+        if HAS_PACKAGING:
+            # Use packaging library for accurate version comparison
+            installed_ver = packaging_version.parse(installed)
+            latest_ver = packaging_version.parse(latest)
+            
+            if installed_ver >= latest_ver:
+                return True, f"Installed version {installed} is up-to-date"
+            else:
+                return False, f"Installed version {installed} < latest version {latest}"
+        else:
+            # Fallback to simple comparison
+            is_up_to_date = _simple_version_compare(installed, latest)
+            if is_up_to_date:
+                return True, f"Installed version {installed} is up-to-date"
+            else:
+                return False, f"Installed version {installed} < latest version {latest}"
+    except Exception:
+        # If version parsing fails, assume up-to-date to avoid false positives
+        return True, "Could not compare versions"
+
+
+def check_version_update(
+    show_notice: bool = True,
+    timeout: float = 1.0
+) -> Optional[str]:
+    """
+    Check if a newer version of Sequenzo is available on PyPI.
+    
+    This function compares the installed version with the latest version
+    on PyPI and optionally displays a notice if an update is available.
+    
+    Args:
+        show_notice: If True, display a notice when update is available (default: True)
+        timeout: Timeout in seconds for PyPI API request (default: 1.0)
+        
+    Returns:
+        Optional[str]: The latest version string if available, None otherwise
+        
+    Examples:
+        >>> from sequenzo.version_check import check_version_update
+        >>> latest = check_version_update(show_notice=True)
+        >>> if latest:
+        ...     print(f"Latest version available: {latest}")
+    """
+    # Get installed version
+    installed = get_installed_version()
+    if not installed:
+        # Can't determine installed version, skip check
+        return None
+    
+    # Get latest version from PyPI
+    latest = get_latest_version_from_pypi(timeout=timeout)
+    if not latest:
+        # Can't get latest version (network issue, etc.), skip
+        return None
+    
+    # Compare versions
+    is_up_to_date, message = compare_versions(installed, latest)
+    
+    # Show notice if update is available
+    if not is_up_to_date and show_notice:
+        print(
+            f"[notice] A new release of sequenzo is available: {installed} -> {latest}",
+            file=sys.stderr
+        )
+        print(
+            f"[notice] To update, run: pip install --upgrade sequenzo=={latest}",
+            file=sys.stderr
+        )
+    
+    return latest
+
+
+def check_version_update_async():
+    """
+    Asynchronously check for version updates without blocking.
+    
+    This function runs the version check in a background thread
+    to avoid blocking the main import process. It's designed to be
+    called during package import.
+    """
+    try:
+        import threading
+        
+        def _check_in_background():
+            """Run version check in background thread."""
+            try:
+                check_version_update(show_notice=True, timeout=1.0)
+            except Exception:
+                # Silently fail - we don't want version checks to break imports
+                pass
+        
+        # Start background thread (daemon thread so it doesn't prevent exit)
+        thread = threading.Thread(target=_check_in_background, daemon=True)
+        thread.start()
+    except Exception:
+        # If threading fails, just skip the check
+        pass
+
+
+if __name__ == "__main__":
+    # Allow manual version check
+    print("Checking for Sequenzo updates...")
+    latest = check_version_update(show_notice=True)
+    if latest:
+        installed = get_installed_version()
+        print(f"\nInstalled version: {installed}")
+        print(f"Latest version: {latest}")
+    else:
+        print("Could not check for updates (network issue or package not found)")

sequenzo/visualization/__init__.py

@@ -0,0 +1,29 @@
+"""
+@Author  : 梁彧祺
+@File    : __init__.py
+@Time    : 11/02/2025 16:42
+@Desc    : 
+"""
+# sequenzo/visualization/__init__.py
+
+from .plot_sequence_index import plot_sequence_index
+from .plot_most_frequent_sequences import plot_most_frequent_sequences
+from .plot_relative_frequency import plot_relative_frequency
+from .plot_transition_matrix import compute_transition_matrix, print_transition_matrix, plot_transition_matrix
+from .plot_mean_time import plot_mean_time
+from .plot_single_medoid import plot_single_medoid, compute_medoids_from_distance_matrix
+from .plot_state_distribution import plot_state_distribution
+from .plot_modal_state import plot_modal_state
+
+
+__all__ = [
+    "plot_mean_time",
+    "plot_most_frequent_sequences",
+    "plot_relative_frequency",
+    "plot_sequence_index",
+    "plot_single_medoid",
+    "plot_state_distribution",
+    "plot_transition_matrix",
+    "plot_modal_state",
+    # Add other functions as needed
+]

sequenzo/visualization/plot_mean_time.py

@@ -0,0 +1,222 @@
+"""
+@Author  : Yuqi Liang 梁彧祺
+@File    : plot_mean_time.py
+@Time    : 14/02/2025 10:12
+@Desc    :
+    Implementation of Mean Time Plot for social sequence analysis,
+    closely following ggseqplot's `ggseqmtplot` function,
+    and TraMineR's `plot.stslist.meant.Rd` for mean time calculation.
+"""
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+from typing import Optional
+from sequenzo.define_sequence_data import SequenceData
+from sequenzo.visualization.utils import (
+    show_plot_title
+)
+
+
+def _compute_mean_time(seqdata: SequenceData, weights="auto") -> pd.DataFrame:
+    """
+    Compute mean total time spent in each state across all sequences.
+    Optimized version using pandas operations.
+
+    :param seqdata: SequenceData object containing sequence information
+    :param weights: (np.ndarray or "auto") Weights for sequences. If "auto", uses seqdata.weights if available
+    :return: DataFrame with mean time spent and standard error for each state
+    """
+    # Process weights
+    if isinstance(weights, str) and weights == "auto":
+        weights = getattr(seqdata, "weights", None)
+    
+    if weights is not None:
+        weights = np.asarray(weights, dtype=float).reshape(-1)
+        if len(weights) != len(seqdata.values):
+            raise ValueError("Length of weights must equal number of sequences.")
+    
+    # Get data and preprocess
+    seq_df = seqdata.to_dataframe()
+    # Use inverse_state_mapping if available, otherwise build it
+    if hasattr(seqdata, 'inverse_state_mapping'):
+        inv = seqdata.inverse_state_mapping
+    else:
+        inv = {v: k for k, v in seqdata.state_mapping.items()}
+    states = list(range(1, len(seqdata.states) + 1))  # Use numerical state indices
+    n = len(seq_df)
+
+    # Get weights
+    if weights is None:
+        w = np.ones(n)
+    else:
+        w = np.asarray(weights, dtype=float)
+
+    # Broadcast weights to each time point
+    W = np.repeat(w[:, None], seq_df.shape[1], axis=1)
+
+    # Convert to long format with weights
+    df_long = seq_df.melt(value_name='state_idx')
+    # Replicate weights for each time point
+    W_long = pd.DataFrame(W, columns=seq_df.columns).melt(value_name='w')['w'].to_numpy()
+    df_long['w'] = W_long
+    # Keep state_idx as numerical for consistent grouping
+    
+    # Calculate mean time spent in each state per sequence
+    # For each sequence, count time spent in each state, then take weighted average
+    seq_state_times = {}
+    for s in states:
+        # Count occurrences of state s in each sequence
+        state_counts = (seq_df == s).sum(axis=1)  # Sum across time for each sequence
+        # Calculate weighted mean across sequences
+        seq_state_times[s] = np.average(state_counts, weights=w) if len(state_counts) > 0 else 0.0
+    
+    mean_times = seq_state_times
+
+    # Calculate standard errors for mean time
+    se = {}
+    n_sequences = len(seq_df)
+    
+    for s in states:
+        if n_sequences > 1:
+            # Count occurrences of state s in each sequence
+            state_counts = (seq_df == s).sum(axis=1)
+            # Calculate weighted standard error
+            weighted_mean = seq_state_times[s]
+            weighted_var = np.average((state_counts - weighted_mean) ** 2, weights=w)
+            # Standard error of the weighted mean
+            se[s] = np.sqrt(weighted_var / n_sequences) if weighted_var >= 0 else 0.0
+        else:
+            se[s] = 0.0
+
+    # Create result DataFrame
+    # Convert state indices to state names, handling missing values
+    state_names = []
+    for s in states:
+        state_name = inv.get(s, None)
+        # Handle np.nan: replace with 'missing'
+        if pd.isna(state_name):
+            state_name = 'missing'
+        # Also handle string 'nan' or 'NaN'
+        elif isinstance(state_name, str) and state_name.lower() == 'nan':
+            state_name = 'missing'
+        state_names.append(state_name)
+    
+    mean_time_df = pd.DataFrame({
+        'State': state_names,
+        'MeanTime': [mean_times[s] for s in states],
+        'StandardError': [se[s] for s in states]
+    })
+
+    mean_time_df.sort_values(by='MeanTime', ascending=True, inplace=True)
+
+    return mean_time_df
+
+
+def plot_mean_time(seqdata: SequenceData,
+                   weights="auto",
+                   show_error_bar: bool = True,
+                   title=None,
+                   x_label="Mean Time",
+                   y_label="State",
+                   fontsize: int = 12,
+                   save_as: Optional[str] = None,
+                   dpi: int = 200) -> None:
+    """
+    Plot Mean Time Plot for sequence data with clean white background.
+
+    :param seqdata: SequenceData object containing sequence information
+    :param weights: (np.ndarray or "auto") Weights for sequences. If "auto", uses seqdata.weights if available
+    :param show_error_bar: Boolean flag to show or hide error bars
+    :param title: Optional title for the plot
+    :param x_label: Label for the x-axis
+    :param y_label: Label for the y-axis
+    :param save_as: Optional file path to save the plot
+    :param dpi: Resolution of the saved plot
+    """
+    # Use default style as base
+    plt.style.use('default')
+
+    # Compute all required data at once
+    mean_time_df = _compute_mean_time(seqdata, weights)
+
+    # Create figure and preallocate memory
+    fig = plt.figure(figsize=(12, 7))
+
+    # Create main plot
+    ax = plt.subplot(111)
+
+    # Get color mapping - use original colors without enhancement
+    cmap = seqdata.get_colormap()
+    colors = [cmap.colors[i] for i in range(len(seqdata.states))]
+
+    # Assign colors to states (without enhancing saturation)
+    mean_time_df['Color'] = pd.Categorical(mean_time_df['State']).codes
+    mean_time_df['Color'] = mean_time_df['Color'].map(lambda x: colors[x])
+
+    # Create custom barplot
+    for i, (_, row) in enumerate(mean_time_df.iterrows()):
+        ax.barh(y=i, width=row['MeanTime'], height=0.7,
+                color=row['Color'], edgecolor='white', linewidth=0.5)
+
+    # Set y-axis ticks and labels
+    # Replace 'nan' with 'missing' for display
+    y_labels = mean_time_df['State'].copy()
+    y_labels = y_labels.replace('nan', 'missing')
+    ax.set_yticks(range(len(mean_time_df)))
+    ax.set_yticklabels(y_labels, fontsize=fontsize-2)
+
+    # Add error bars if needed
+    if show_error_bar:
+        ax.errorbar(
+            x=mean_time_df["MeanTime"],
+            y=range(len(mean_time_df)),
+            xerr=mean_time_df["StandardError"],
+            fmt='none',
+            ecolor='black',
+            capsize=3,
+            capthick=1,
+            elinewidth=1.5
+        )
+
+    # Set plot properties
+    if title:
+        show_plot_title(ax, title, show=True, fontsize=fontsize+2, fontweight='bold', pad=20)
+    ax.set_xlabel(x_label, fontsize=fontsize)
+    ax.set_ylabel(y_label, fontsize=fontsize, labelpad=15)
+
+    # Clean white background with light grid
+    ax.set_facecolor('white')
+    ax.grid(axis='x', color='#E0E0E0', linestyle='-', linewidth=0.5)
+    ax.set_axisbelow(True)  # Place grid lines behind the bars
+
+    # Customize borders
+    for spine in ax.spines.values():
+        spine.set_color('#CCCCCC')  # Light gray border
+        spine.set_linewidth(0.5)
+
+    # Adjust layout(1/2)
+    plt.subplots_adjust(left=0.3)
+
+    # Add a note about normalization
+    relative_threshold = 0.01
+    max_val = mean_time_df['MeanTime'].max()
+    too_many_small = np.sum(mean_time_df['MeanTime'] < relative_threshold * max_val) >= 1
+    if too_many_small:
+        norm_note = f"Note: Some bars may appear as zero, but actually have small non-zero values."
+        plt.figtext(0.5, -0.02, norm_note, ha='center', fontsize=fontsize-2, style='italic')
+
+    # Adjust layout before saving
+    plt.tight_layout()
+
+    # Handle save_as extension
+    if save_as and not save_as.lower().endswith(('.png', '.jpg', '.jpeg', '.pdf')):
+        save_as = save_as + '.png'
+
+    # Save figure if needed
+    if save_as:
+        fig.savefig(save_as, dpi=dpi, bbox_inches='tight', facecolor='white')
+
+    # Display plot
+    plt.show()
+    plt.close()
+