PyMSAStats 0.1.0__py3-none-any.whl

msa_stats_calculator.py

@@ -0,0 +1,485 @@
+# ABOUTME: Core implementation of MSA summary statistics calculator.
+# ABOUTME: Computes 27 metrics matching the original C++ msastats behavior.
+"""MSA Statistics Calculator.
+
+A Python implementation of the MsaStatsCalculator for computing MSA summary statistics.
+"""
+import enum
+from pathlib import Path
+from typing import List, Dict, Tuple, Union
+
+
+class MsaStatsError(Exception):
+    """Base exception for MSA statistics errors."""
+    pass
+
+class StatType(enum.Enum):
+    """Defines the types of summary statistics that can be calculated."""
+    AVG_GAP_SIZE = enum.auto()
+    MSA_LEN = enum.auto()
+    LONGEST_UNALIGNED_SEQ = enum.auto()
+    SHORTEST_UNALIGNED_SEQ = enum.auto()
+    TOT_NUM_GAPS = enum.auto()
+    NUM_GAPS_LEN_ONE = enum.auto()
+    NUM_GAPS_LEN_TWO = enum.auto()
+    NUM_GAPS_LEN_THREE = enum.auto()
+    NUM_GAPS_LEN_AT_LEAST_FOUR = enum.auto()
+    AVG_UNIQUE_GAP_SIZE = enum.auto()
+    TOT_NUM_UNIQUE_GAPS = enum.auto()
+    NUM_GAPS_LEN_ONE_IN_ONE_SEQ = enum.auto()
+    NUM_GAPS_LEN_ONE_IN_TWO_SEQS = enum.auto()
+    NUM_GAPS_LEN_ONE_IN_ALL_EXCEPT_ONE = enum.auto()
+    NUM_GAPS_LEN_TWO_IN_ONE_SEQ = enum.auto()
+    NUM_GAPS_LEN_TWO_IN_TWO_SEQS = enum.auto()
+    NUM_GAPS_LEN_TWO_IN_ALL_EXCEPT_ONE = enum.auto()
+    NUM_GAPS_LEN_THREE_IN_ONE_SEQ = enum.auto()
+    NUM_GAPS_LEN_THREE_IN_TWO_SEQS = enum.auto()
+    NUM_GAPS_LEN_THREE_IN_ALL_EXCEPT_ONE = enum.auto()
+    NUM_GAPS_LEN_AT_LEAST_FOUR_IN_ONE_SEQ = enum.auto()
+    NUM_GAPS_LEN_AT_LEAST_FOUR_IN_TWO_SEQS = enum.auto()
+    NUM_GAPS_LEN_AT_LEAST_FOUR_IN_ALL_EXCEPT_ONE = enum.auto()
+    MSA_POSITION_WITH_0_GAPS = enum.auto()
+    MSA_POSITION_WITH_1_GAPS = enum.auto()
+    MSA_POSITION_WITH_2_GAPS = enum.auto()
+    MSA_POSITION_WITH_N_MINUS_1_GAPS = enum.auto()
+
+
+class MsaStatsCalculator:
+    """
+    Calculates a variety of summary statistics for a given Multiple Sequence Alignment (MSA).
+    The algorithms and data structures are designed to mirror the original C++ implementation.
+    """
+
+    def __init__(self, msa_sequences: List[str]):
+        """Initializes the calculator with an MSA provided as a list of strings.
+
+        Args:
+            msa_sequences: A list of strings, where each string is an aligned sequence.
+
+        Raises:
+            ValueError: If input is empty, contains non-strings, has empty sequences,
+                or sequences have mismatched lengths.
+        """
+        if not msa_sequences:
+            raise ValueError("Input must be a non-empty list of sequences.")
+
+        for i, seq in enumerate(msa_sequences):
+            if not isinstance(seq, str):
+                raise ValueError(
+                    f"Sequence at index {i} is not a string (got {type(seq).__name__})."
+                )
+
+        self._original_aligned_seqs: Tuple[str, ...] = tuple(msa_sequences)
+        self._number_of_sequences: int = len(self._original_aligned_seqs)
+
+        if not self._original_aligned_seqs[0]:
+            raise ValueError("Sequences cannot be empty.")
+
+        self._msa_length = len(self._original_aligned_seqs[0])
+        for i, seq in enumerate(self._original_aligned_seqs[1:], start=1):
+            if len(seq) != self._msa_length:
+                raise ValueError(
+                    f"Sequence length mismatch: sequence 0 has length {self._msa_length}, "
+                    f"but sequence {i} has length {len(seq)}."
+                )
+
+        self._initialize_all_variables()
+
+    @classmethod
+    def from_fasta(cls, fasta_path: Union[str, Path]) -> 'MsaStatsCalculator':
+        """Creates an MsaStatsCalculator instance from a FASTA file.
+
+        Args:
+            fasta_path: The path to the FASTA file.
+
+        Returns:
+            An instance of MsaStatsCalculator.
+
+        Raises:
+            MsaStatsError: If the file cannot be read or contains no sequences.
+            ValueError: If the parsed sequences are invalid (empty, mismatched lengths).
+        """
+        fasta_path = Path(fasta_path)
+        try:
+            with open(fasta_path, 'r') as f:
+                sequences = []
+                current_seq = ""
+                for line in f:
+                    line = line.strip()
+                    if line.startswith('>'):
+                        if current_seq:
+                            sequences.append(current_seq)
+                        current_seq = ""
+                    else:
+                        current_seq += line
+                if current_seq:
+                    sequences.append(current_seq)
+        except FileNotFoundError as e:
+            raise MsaStatsError(f"FASTA file not found: {fasta_path}") from e
+        except PermissionError as e:
+            raise MsaStatsError(f"Permission denied reading FASTA file: {fasta_path}") from e
+        except IsADirectoryError as e:
+            raise MsaStatsError(f"Path is a directory, not a file: {fasta_path}") from e
+        except OSError as e:
+            raise MsaStatsError(f"Failed to read FASTA file '{fasta_path}': {e}") from e
+
+        if not sequences:
+            raise MsaStatsError(f"No sequences found in FASTA file: {fasta_path}")
+
+        return cls(sequences)
+
+    def _initialize_all_variables(self) -> None:
+        """Resets all internal statistics and working data structures."""
+        self._aligned_seqs: List[str] = list(self._original_aligned_seqs)
+
+        # Core data structures
+        self._unique_indel_map: Dict[Tuple[int, int], List[int]] = {}
+        self._indel_counter: List[int] = []
+
+        # Final statistics attributes
+        self._ave_indel_length: float = 0.0
+        self._total_number_of_indels: int = 0
+        self._longest_seq_length: int = 0
+        self._shortest_seq_length: int = 0
+
+        self._number_of_indels_of_length_one: int = 0
+        self._number_of_indels_of_length_two: int = 0
+        self._number_of_indels_of_length_three: int = 0
+        self._number_of_indels_of_length_at_least_four: int = 0
+
+        self._number_of_indels_of_length_one_in_one_position: int = 0
+        self._number_of_indels_of_length_one_in_two_positions: int = 0
+        self._number_of_indels_of_length_one_in_n_minus_1_positions: int = 0
+
+        self._number_of_indels_of_length_two_in_one_position: int = 0
+        self._number_of_indels_of_length_two_in_two_positions: int = 0
+        self._number_of_indels_of_length_two_in_n_minus_1_positions: int = 0
+
+        self._number_of_indels_of_length_three_in_one_position: int = 0
+        self._number_of_indels_of_length_three_in_two_positions: int = 0
+        self._number_of_indels_of_length_three_in_n_minus_1_positions: int = 0
+
+        self._number_of_indels_of_length_at_least_four_in_one_position: int = 0
+        self._number_of_indels_of_length_at_least_four_in_two_positions: int = 0
+        self._number_of_indels_of_length_at_least_four_in_n_minus_1_positions: int = 0
+
+        self._number_of_msa_position_with_0_gaps: int = 0
+        self._number_of_msa_position_with_1_gaps: int = 0
+        self._number_of_msa_position_with_2_gaps: int = 0
+        self._number_of_msa_position_with_n_minus_1_gaps: int = 0
+
+        # Unique indels summary statistics
+        self._ave_unique_indel_length: float = 0.0
+        self._total_number_of_unique_indels: int = 0
+
+    def _trim_msa_from_all_indel_position_and_get_summary_statistics_from_indel_counter(self) -> None:
+        """
+        Counts gaps per column, calculates column-based stats, and trims all-gap columns.
+        This method modifies self._aligned_seqs.
+        """
+        if not self._original_aligned_seqs:
+            return
+
+        self._indel_counter = [0] * self._msa_length
+        for seq in self._original_aligned_seqs:
+            for i, char in enumerate(seq):
+                if char == '-':
+                    self._indel_counter[i] += 1
+
+        for count in self._indel_counter:
+            if count == 0:
+                self._number_of_msa_position_with_0_gaps += 1
+            elif count == 1:
+                self._number_of_msa_position_with_1_gaps += 1
+            elif count == 2:
+                self._number_of_msa_position_with_2_gaps += 1
+            elif count == self._number_of_sequences - 1:
+                self._number_of_msa_position_with_n_minus_1_gaps += 1
+        
+        # Identify columns to keep
+        cols_to_keep = [i for i, count in enumerate(self._indel_counter) if count < self._number_of_sequences]
+
+        # Create new sequences with only the columns to keep
+        self._aligned_seqs = [''.join(seq[i] for i in cols_to_keep) for seq in self._original_aligned_seqs]
+
+
+    def _fill_unique_gaps_map(self) -> None:
+        """
+        Scans the aligned sequences to identify and count unique indel events,
+        populating the _unique_indel_map.
+        """
+        self._unique_indel_map.clear()
+        if not self._aligned_seqs:
+            return
+            
+        msa_length = len(self._aligned_seqs[0])
+
+        for seq in self._aligned_seqs:
+            in_indel = False
+            start_index = -1
+
+            for i, char in enumerate(seq):
+                if char == '-' and not in_indel:
+                    in_indel = True
+                    start_index = i
+                elif char != '-' and in_indel:
+                    # End of the indel, record it
+                    end_index = i - 1
+                    key = (start_index, end_index)
+                    length = end_index - start_index + 1
+                    
+                    if key not in self._unique_indel_map:
+                        self._unique_indel_map[key] = [length, 0]
+                    self._unique_indel_map[key][1] += 1
+                    
+                    in_indel = False
+                    start_index = -1
+
+            # Handle indel that goes to the end of the sequence
+            if in_indel:
+                end_index = msa_length - 1
+                key = (start_index, end_index)
+                length = end_index - start_index + 1
+                if key not in self._unique_indel_map:
+                    self._unique_indel_map[key] = [length, 0]
+                self._unique_indel_map[key][1] += 1
+
+    def _set_values_of_indel_summ_stats(self) -> None:
+        """
+        Calculates indel-related summary statistics by processing the _unique_indel_map.
+        """
+        self._fill_unique_gaps_map()
+
+        total_gap_chars = 0
+        total_unique_gap_chars = 0
+
+        for (length, count) in self._unique_indel_map.values():
+            self._total_number_of_indels += count
+            self._total_number_of_unique_indels += 1
+            total_gap_chars += length * count
+            total_unique_gap_chars += length
+
+            if length == 1:
+                self._number_of_indels_of_length_one += count
+                if count == 1:
+                    self._number_of_indels_of_length_one_in_one_position += 1
+                if count == 2:
+                    self._number_of_indels_of_length_one_in_two_positions += 1
+                if count == self._number_of_sequences - 1:
+                    self._number_of_indels_of_length_one_in_n_minus_1_positions += 1
+            elif length == 2:
+                self._number_of_indels_of_length_two += count
+                if count == 1:
+                    self._number_of_indels_of_length_two_in_one_position += 1
+                if count == 2:
+                    self._number_of_indels_of_length_two_in_two_positions += 1
+                if count == self._number_of_sequences - 1:
+                    self._number_of_indels_of_length_two_in_n_minus_1_positions += 1
+            elif length == 3:
+                self._number_of_indels_of_length_three += count
+                if count == 1:
+                    self._number_of_indels_of_length_three_in_one_position += 1
+                if count == 2:
+                    self._number_of_indels_of_length_three_in_two_positions += 1
+                if count == self._number_of_sequences - 1:
+                    self._number_of_indels_of_length_three_in_n_minus_1_positions += 1
+            else: # length >= 4
+                self._number_of_indels_of_length_at_least_four += count
+                if count == 1:
+                    self._number_of_indels_of_length_at_least_four_in_one_position += 1
+                if count == 2:
+                    self._number_of_indels_of_length_at_least_four_in_two_positions += 1
+                if count == self._number_of_sequences - 1:
+                    self._number_of_indels_of_length_at_least_four_in_n_minus_1_positions += 1
+
+        if self._total_number_of_indels > 0:
+            self._ave_indel_length = total_gap_chars / self._total_number_of_indels
+        if self._total_number_of_unique_indels > 0:
+            self._ave_unique_indel_length = total_unique_gap_chars / self._total_number_of_unique_indels
+
+    def _set_longest_and_shortest_sequence_lengths(self) -> None:
+        """Calculates the longest and shortest ungapped sequence lengths."""
+        if not self._original_aligned_seqs:
+            self._longest_seq_length = 0
+            self._shortest_seq_length = 0
+            return
+
+        seq_lengths = [len(s.replace('-', '')) for s in self._original_aligned_seqs]
+        self._longest_seq_length = max(seq_lengths)
+        self._shortest_seq_length = min(seq_lengths)
+
+
+    def recompute_stats(self) -> None:
+        """
+        The main public method to run the full statistical analysis.
+        This orchestrates the calls to the internal calculation methods in the correct order.
+        """
+        self._initialize_all_variables()
+        self._trim_msa_from_all_indel_position_and_get_summary_statistics_from_indel_counter()
+        self._set_values_of_indel_summ_stats()
+        self._set_longest_and_shortest_sequence_lengths()
+
+    def get_stat_by_type(self, stat_type: StatType) -> float:
+        """
+        Returns the value of a specific statistic.
+
+        Args:
+            stat_type: The enum member representing the statistic to retrieve.
+
+        Returns:
+            The calculated value of the statistic as a float.
+        """
+        stat_map = {
+            StatType.AVG_GAP_SIZE: self.average_indel_size,
+            StatType.MSA_LEN: self.msa_length,
+            StatType.LONGEST_UNALIGNED_SEQ: self.msa_longest_seq_length,
+            StatType.SHORTEST_UNALIGNED_SEQ: self.msa_shortest_seq_length,
+            StatType.TOT_NUM_GAPS: self.total_number_of_indels,
+            StatType.NUM_GAPS_LEN_ONE: self.number_of_indels_of_length_one,
+            StatType.NUM_GAPS_LEN_TWO: self.number_of_indels_of_length_two,
+            StatType.NUM_GAPS_LEN_THREE: self.number_of_indels_of_length_three,
+            StatType.NUM_GAPS_LEN_AT_LEAST_FOUR: self.number_of_indels_of_length_at_least_four,
+            StatType.AVG_UNIQUE_GAP_SIZE: self.average_unique_indel_size,
+            StatType.TOT_NUM_UNIQUE_GAPS: self.total_number_of_unique_indels,
+            StatType.NUM_GAPS_LEN_ONE_IN_ONE_SEQ: self.number_of_indels_of_length_one_in_one_position,
+            StatType.NUM_GAPS_LEN_ONE_IN_TWO_SEQS: self.number_of_indels_of_length_one_in_two_positions,
+            StatType.NUM_GAPS_LEN_ONE_IN_ALL_EXCEPT_ONE: self.number_of_indels_of_length_one_in_n_minus_1_positions,
+            StatType.NUM_GAPS_LEN_TWO_IN_ONE_SEQ: self.number_of_indels_of_length_two_in_one_position,
+            StatType.NUM_GAPS_LEN_TWO_IN_TWO_SEQS: self.number_of_indels_of_length_two_in_two_positions,
+            StatType.NUM_GAPS_LEN_TWO_IN_ALL_EXCEPT_ONE: self.number_of_indels_of_length_two_in_n_minus_1_positions,
+            StatType.NUM_GAPS_LEN_THREE_IN_ONE_SEQ: self.number_of_indels_of_length_three_in_one_position,
+            StatType.NUM_GAPS_LEN_THREE_IN_TWO_SEQS: self.number_of_indels_of_length_three_in_two_positions,
+            StatType.NUM_GAPS_LEN_THREE_IN_ALL_EXCEPT_ONE: self.number_of_indels_of_length_three_in_n_minus_1_positions,
+            StatType.NUM_GAPS_LEN_AT_LEAST_FOUR_IN_ONE_SEQ: self.number_of_indels_of_length_at_least_four_in_one_position,
+            StatType.NUM_GAPS_LEN_AT_LEAST_FOUR_IN_TWO_SEQS: self.number_of_indels_of_length_at_least_four_in_two_positions,
+            StatType.NUM_GAPS_LEN_AT_LEAST_FOUR_IN_ALL_EXCEPT_ONE: self.number_of_indels_of_length_at_least_four_in_n_minus_1_positions,
+            StatType.MSA_POSITION_WITH_0_GAPS: self.number_of_msa_position_with_0_gaps,
+            StatType.MSA_POSITION_WITH_1_GAPS: self.number_of_msa_position_with_1_gaps,
+            StatType.MSA_POSITION_WITH_2_GAPS: self.number_of_msa_position_with_2_gaps,
+            StatType.MSA_POSITION_WITH_N_MINUS_1_GAPS: self.number_of_msa_position_with_n_minus_1_gaps,
+        }
+        return float(stat_map.get(stat_type, -1.0))
+
+    def get_stat_vec(self) -> List[float]:
+        """
+        Returns a list of all summary statistics in a predefined order, matching
+        the C++ implementation's `getStatVec` method.
+        """
+        return [self.get_stat_by_type(stat) for stat in StatType]
+
+    def __str__(self) -> str:
+        """Returns a string representation of the original aligned MSA."""
+        return "\n".join(self._original_aligned_seqs)
+
+    # Public properties for accessing statistics
+    @property
+    def msa_length(self) -> int:
+        return self._msa_length
+
+    @property
+    def number_of_sequences(self) -> int:
+        return self._number_of_sequences
+
+    @property
+    def total_number_of_indels(self) -> int:
+        return self._total_number_of_indels
+
+    @property
+    def total_number_of_unique_indels(self) -> int:
+        return self._total_number_of_unique_indels
+
+    @property
+    def number_of_indels_of_length_one(self) -> int:
+        return self._number_of_indels_of_length_one
+
+    @property
+    def number_of_indels_of_length_two(self) -> int:
+        return self._number_of_indels_of_length_two
+
+    @property
+    def number_of_indels_of_length_three(self) -> int:
+        return self._number_of_indels_of_length_three
+
+    @property
+    def number_of_indels_of_length_at_least_four(self) -> int:
+        return self._number_of_indels_of_length_at_least_four
+
+    @property
+    def average_indel_size(self) -> float:
+        return self._ave_indel_length
+
+    @property
+    def average_unique_indel_size(self) -> float:
+        return self._ave_unique_indel_length
+
+    @property
+    def msa_longest_seq_length(self) -> int:
+        return self._longest_seq_length
+
+    @property
+    def msa_shortest_seq_length(self) -> int:
+        return self._shortest_seq_length
+
+    @property
+    def number_of_indels_of_length_one_in_one_position(self) -> int:
+        return self._number_of_indels_of_length_one_in_one_position
+
+    @property
+    def number_of_indels_of_length_one_in_two_positions(self) -> int:
+        return self._number_of_indels_of_length_one_in_two_positions
+
+    @property
+    def number_of_indels_of_length_one_in_n_minus_1_positions(self) -> int:
+        return self._number_of_indels_of_length_one_in_n_minus_1_positions
+
+    @property
+    def number_of_indels_of_length_two_in_one_position(self) -> int:
+        return self._number_of_indels_of_length_two_in_one_position
+
+    @property
+    def number_of_indels_of_length_two_in_two_positions(self) -> int:
+        return self._number_of_indels_of_length_two_in_two_positions
+
+    @property
+    def number_of_indels_of_length_two_in_n_minus_1_positions(self) -> int:
+        return self._number_of_indels_of_length_two_in_n_minus_1_positions
+
+    @property
+    def number_of_indels_of_length_three_in_one_position(self) -> int:
+        return self._number_of_indels_of_length_three_in_one_position
+
+    @property
+    def number_of_indels_of_length_three_in_two_positions(self) -> int:
+        return self._number_of_indels_of_length_three_in_two_positions
+
+    @property
+    def number_of_indels_of_length_three_in_n_minus_1_positions(self) -> int:
+        return self._number_of_indels_of_length_three_in_n_minus_1_positions
+
+    @property
+    def number_of_indels_of_length_at_least_four_in_one_position(self) -> int:
+        return self._number_of_indels_of_length_at_least_four_in_one_position
+
+    @property
+    def number_of_indels_of_length_at_least_four_in_two_positions(self) -> int:
+        return self._number_of_indels_of_length_at_least_four_in_two_positions
+
+    @property
+    def number_of_indels_of_length_at_least_four_in_n_minus_1_positions(self) -> int:
+        return self._number_of_indels_of_length_at_least_four_in_n_minus_1_positions
+
+    @property
+    def number_of_msa_position_with_0_gaps(self) -> int:
+        return self._number_of_msa_position_with_0_gaps
+
+    @property
+    def number_of_msa_position_with_1_gaps(self) -> int:
+        return self._number_of_msa_position_with_1_gaps
+
+    @property
+    def number_of_msa_position_with_2_gaps(self) -> int:
+        return self._number_of_msa_position_with_2_gaps
+
+    @property
+    def number_of_msa_position_with_n_minus_1_gaps(self) -> int:
+        return self._number_of_msa_position_with_n_minus_1_gaps

msastats.py

@@ -0,0 +1,49 @@
+# ABOUTME: Drop-in API module for msastats (import as `msastats`).
+# ABOUTME: Provides calculate_msa_stats, calculate_fasta_stats, and stats_names.
+"""Pure-Python replacement for the `msastats` extension module.
+
+This module implements the minimal public API used by MSACompare:
+  - calculate_msa_stats(msa: list[str]) -> list[float]
+  - calculate_fasta_stats(path: str) -> list[float]
+  - stats_names() -> list[str]
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import List, Sequence, Union
+
+from msa_stats_calculator import MsaStatsCalculator, MsaStatsError, StatType
+
+__all__ = [
+    "MsaStatsCalculator",
+    "MsaStatsError",
+    "StatType",
+    "calculate_fasta_stats",
+    "calculate_msa_stats",
+    "stats_names",
+]
+
+
+PathLike = Union[str, os.PathLike[str]]
+
+
+def calculate_msa_stats(msa: Sequence[str]) -> List[float]:
+    """Calculate stats from an in-memory MSA (list/tuple of aligned strings)."""
+    calculator = MsaStatsCalculator(list(msa))
+    calculator.recompute_stats()
+    return calculator.get_stat_vec()
+
+
+def calculate_fasta_stats(fasta_path: PathLike) -> List[float]:
+    """Calculate stats from a FASTA file containing an aligned MSA."""
+    calculator = MsaStatsCalculator.from_fasta(Path(fasta_path))
+    calculator.recompute_stats()
+    return calculator.get_stat_vec()
+
+
+def stats_names() -> List[str]:
+    """Return stat names in the same order as `calculate_*_stats`."""
+    return [stat.name for stat in StatType]
+

pymsastats-0.1.0.dist-info/METADATA

@@ -0,0 +1,328 @@
+Metadata-Version: 2.4
+Name: PyMSAStats
+Version: 0.1.0
+Summary: Pure-Python MSA summary statistics
+Author: Naiel J
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/naielj/PyMSAStats
+Project-URL: Repository, https://github.com/naielj/PyMSAStats
+Project-URL: Issues, https://github.com/naielj/PyMSAStats/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# PyMSAStats (pure-Python `msastats`)
+
+A pure-Python implementation of the `msastats` API used by MSACompare for computing
+Multiple Sequence Alignment (MSA) summary statistics.
+
+This package installs and imports as `msastats`:
+
+```python
+import msastats
+```
+
+## Usage
+
+You can use either the high-level `msastats` functions (drop-in API), or the
+lower-level `MsaStatsCalculator`.
+
+### Installation
+
+Install from PyPI:
+
+```bash
+pip install pymsastats
+```
+
+Or with `uv`:
+
+```bash
+uv add pymsastats
+```
+
+For development (editable install from source):
+
+```bash
+git clone https://github.com/naielj/PyMSAStats.git
+cd PyMSAStats
+uv sync
+```
+
+### Drop-in API (Recommended)
+
+From a list of aligned sequences:
+
+```python
+import msastats
+
+stats = msastats.calculate_msa_stats(["AA-A", "AA-A", "A--A"])
+names = msastats.stats_names()
+
+as_dict = dict(zip(names, stats))
+print(as_dict["AVG_GAP_SIZE"])
+```
+
+From an aligned FASTA file:
+
+```python
+import msastats
+
+stats = msastats.calculate_fasta_stats("path/to/alignment.fasta")
+print(stats)
+```
+
+### Calculator API
+
+From a list of aligned sequences:
+
+```python
+from msastats import MsaStatsCalculator, StatType
+
+# 1. Initialize with a list of aligned sequences
+sequences = [
+    "AC--GT",
+    "ACGTGT",
+    "AC-TGT",
+]
+calculator = MsaStatsCalculator(sequences)
+
+# 2. Compute the statistics
+calculator.recompute_stats()
+
+# 3. Access the statistics
+print(f"MSA Length: {calculator.msa_length}")
+print(f"Number of Sequences: {calculator.number_of_sequences}")
+print(f"Total Gaps: {calculator.total_number_of_indels}")
+
+# Or access stats by type
+avg_gap_size = calculator.get_stat_by_type(StatType.AVG_GAP_SIZE)
+print(f"Average Gap Size: {avg_gap_size:.2f}")
+
+# Get all stats as a vector
+stats_vector = calculator.get_stat_vec()
+print(f"Stats Vector: {stats_vector}")
+```
+
+From an aligned FASTA file:
+
+```python
+from pathlib import Path
+from msastats import MsaStatsCalculator, StatType
+
+# 1. Create a dummy FASTA file
+fasta_content = """>seq1
+AC--GT--
+>seq2
+ACGTGT--
+>seq3
+AC-TGTAC
+"""
+fasta_path = Path("dummy.fasta")
+fasta_path.write_text(fasta_content)
+
+# 2. Initialize from the FASTA file
+calculator = MsaStatsCalculator.from_fasta(fasta_path)
+
+# 3. Compute the statistics
+calculator.recompute_stats()
+
+# 4. Access the statistics
+print(f"MSA Length: {calculator.msa_length}")
+print(f"Longest Sequence: {calculator.msa_longest_seq_length}")
+print(f"Shortest Sequence: {calculator.msa_shortest_seq_length}")
+print(f"Total Number of Gaps: {calculator.total_number_of_indels}")
+
+# Clean up the dummy file
+fasta_path.unlink()
+```
+
+## Statistics reference (27 metrics)
+
+The 27 summary statistics implemented here are defined in:
+
+> Wygoda E, Loewenthal G, Moshe A, Alburquerque M, Mayrose I, Pupko T. Statistical framework to determine indel-length distribution. *Bioinformatics*. 2024;40(2):btae043. <https://doi.org/10.1093/bioinformatics/btae043>
+
+```bibtex
+@article{wygoda2024indel,
+    author = {Wygoda, Elya and Loewenthal, Gil and Moshe, Asher and Alburquerque, Michael and Mayrose, Itay and Pupko, Tal},
+    title = {Statistical framework to determine indel-length distribution},
+    journal = {Bioinformatics},
+    volume = {40},
+    number = {2},
+    pages = {btae043},
+    year = {2024},
+    doi = {10.1093/bioinformatics/btae043}
+}
+```
+
+For an illustrated reference with a worked example showing all 27 metric values on a single MSA, see
+[docs/summary_statistics_reference.md](docs/summary_statistics_reference.md).
+
+### Terminology
+
+- **Gap character:** the implementation treats `-` as a gap.
+- **All-gap column:** a column where *all* sequences have `-` at that position.
+- **Gap run / indel (what “gap” means in most metrics):** a maximal contiguous run of `-` in a single sequence.
+- **All-gap trimming (important):** before detecting gap runs, the algorithm removes all-gap columns. This matches the
+  original C++ implementation and prevents all-gap columns from splitting/creating gap runs.
+- **Unique gap interval:** gap runs are grouped by their `(start, end)` coordinates *in the trimmed alignment*. If
+  multiple sequences have a gap run with the same `(start, end)`, that is **one** unique gap interval with:
+  - `length = end - start + 1`
+  - `count = number of sequences that have that exact interval`
+
+### Returned order
+
+`calculate_msa_stats` / `calculate_fasta_stats` return a list of 27 floats in the same order as
+`msastats.stats_names()` (and the `StatType` enum).
+
+### Metric definitions
+
+#### Alignment and sequence lengths
+
+- `MSA_LEN` (MSACompare: `LINE_LENGTH`): alignment length in columns (includes all-gap columns).
+- `LONGEST_UNALIGNED_SEQ` (MSACompare: `LONGEST_UNALIGNED_SEQ_LENGTH`): max ungapped sequence length across sequences
+  (`len(seq.replace('-', ''))`).
+- `SHORTEST_UNALIGNED_SEQ` (MSACompare: `SHORTEST_UNALIGNED_SEQ_LENGTH`): min ungapped sequence length across sequences.
+
+#### Gap-run totals (after all-gap trimming)
+
+Let the set of unique gap intervals be `U`, and for each `u ∈ U`, let `u.length` be its length and `u.count` be how
+many sequences contain that interval.
+
+- `TOT_NUM_GAPS` (MSACompare: `TOTAL_GAPS`): total number of gap runs across sequences:
+  `Σ_u u.count`
+- `AVG_GAP_SIZE` (MSACompare: `AVG_LENGTH_OF_GAPS`): mean gap-run length across all sequences:
+  `(Σ_u u.length · u.count) / TOT_NUM_GAPS` (0 if `TOT_NUM_GAPS == 0`)
+- `NUM_GAPS_LEN_ONE` (MSACompare: `GAPS_OF_LENGTH_ONE`): `Σ_{u.length==1} u.count`
+- `NUM_GAPS_LEN_TWO` (MSACompare: `GAPS_OF_LENGTH_TWO`): `Σ_{u.length==2} u.count`
+- `NUM_GAPS_LEN_THREE` (MSACompare: `GAPS_OF_LENGTH_THREE`): `Σ_{u.length==3} u.count`
+- `NUM_GAPS_LEN_AT_LEAST_FOUR` (MSACompare: `GAPS_LARGER_THAN_THREE`): `Σ_{u.length>=4} u.count`
+
+#### Unique gap intervals (after all-gap trimming)
+
+- `TOT_NUM_UNIQUE_GAPS` (MSACompare: `TOTAL_UNIQUE_GAPS`): number of unique gap intervals: `|U|`
+- `AVG_UNIQUE_GAP_SIZE` (MSACompare: `AVG_SIZE_OF_UNIQUE_GAPS`): mean unique-gap length:
+  `(Σ_u u.length) / TOT_NUM_UNIQUE_GAPS` (0 if `TOT_NUM_UNIQUE_GAPS == 0`)
+
+#### Unique gap intervals shared by k sequences (after all-gap trimming)
+
+These count **unique** gap intervals (not total occurrences). For a given interval length bucket, they count how many
+intervals have `u.count == k`.
+
+Length 1:
+- `NUM_GAPS_LEN_ONE_IN_ONE_SEQ` (MSACompare: `GAPS_LENGTH_ONE_ONE_SEQ`): `|{u: u.length==1 and u.count==1}|`
+- `NUM_GAPS_LEN_ONE_IN_TWO_SEQS` (MSACompare: `GAPS_LENGTH_ONE_TWO_SEQ`): `|{u: u.length==1 and u.count==2}|`
+- `NUM_GAPS_LEN_ONE_IN_ALL_EXCEPT_ONE` (MSACompare: `GAPS_LENGTH_ONE_EXCEPT_ONE`):
+  `|{u: u.length==1 and u.count==N-1}|`
+
+Length 2:
+- `NUM_GAPS_LEN_TWO_IN_ONE_SEQ` (MSACompare: `GAPS_LENGTH_TWO_ONE_SEQ`): `|{u: u.length==2 and u.count==1}|`
+- `NUM_GAPS_LEN_TWO_IN_TWO_SEQS` (MSACompare: `GAPS_LENGTH_TWO_TWO_SEQ`): `|{u: u.length==2 and u.count==2}|`
+- `NUM_GAPS_LEN_TWO_IN_ALL_EXCEPT_ONE` (MSACompare: `GAPS_LENGTH_TWO_EXCEPT_ONE`):
+  `|{u: u.length==2 and u.count==N-1}|`
+
+Length 3:
+- `NUM_GAPS_LEN_THREE_IN_ONE_SEQ` (MSACompare: `GAPS_LENGTH_THREE_ONE_SEQ`): `|{u: u.length==3 and u.count==1}|`
+- `NUM_GAPS_LEN_THREE_IN_TWO_SEQS` (MSACompare: `GAPS_LENGTH_THREE_TWO_SEQ`): `|{u: u.length==3 and u.count==2}|`
+- `NUM_GAPS_LEN_THREE_IN_ALL_EXCEPT_ONE` (MSACompare: `GAPS_LENGTH_THREE_EXCEPT_ONE`):
+  `|{u: u.length==3 and u.count==N-1}|`
+
+Length ≥ 4:
+- `NUM_GAPS_LEN_AT_LEAST_FOUR_IN_ONE_SEQ` (MSACompare: `GAPS_LARGER_THAN_THREE_ONE_SEQ`):
+  `|{u: u.length>=4 and u.count==1}|`
+- `NUM_GAPS_LEN_AT_LEAST_FOUR_IN_TWO_SEQS` (MSACompare: `GAPS_LARGER_THAN_THREE_TWO_SEQ`):
+  `|{u: u.length>=4 and u.count==2}|`
+- `NUM_GAPS_LEN_AT_LEAST_FOUR_IN_ALL_EXCEPT_ONE` (MSACompare: `GAPS_LARGER_THAN_THREE_EXCEPT_ONE`):
+  `|{u: u.length>=4 and u.count==N-1}|`
+
+Important edge-case note: to match the C++ reference, the "`== 1` / `== 2` / `== N-1`" checks are independent.
+So for small `N`, some categories overlap:
+- If `N == 2`, then `N-1 == 1`, so "`IN_ONE_SEQ`" and "`IN_ALL_EXCEPT_ONE`" count the same intervals.
+- If `N == 3`, then `N-1 == 2`, so "`IN_TWO_SEQS`" and "`IN_ALL_EXCEPT_ONE`" count the same intervals.
+
+#### Column-wise gap counts (computed on the original alignment, before all-gap trimming)
+
+These count alignment columns based on how many sequences have a `-` in that column:
+
+- `MSA_POSITION_WITH_0_GAPS` (MSACompare: `NO_GAP_COLUMNS`): number of columns with exactly 0 gaps
+- `MSA_POSITION_WITH_1_GAPS` (MSACompare: `ONE_GAP_COLUMNS`): number of columns with exactly 1 gap
+- `MSA_POSITION_WITH_2_GAPS` (MSACompare: `TWO_GAP_COLUMNS`): number of columns with exactly 2 gaps
+- `MSA_POSITION_WITH_N_MINUS_1_GAPS` (MSACompare: `ONE_GAP_EXCEPT_ONE_COLUMN`): number of columns with exactly `N-1` gaps
+
+Notes:
+- Columns with `N` gaps (all-gap columns) are **not** counted in any of these buckets.
+- For `N == 3`, the `N-1` bucket is effectively 0 because columns with 2 gaps are already counted in
+  `MSA_POSITION_WITH_2_GAPS` (this matches the C++ reference behavior).
+
+### Examples
+
+Helper to get a readable dict:
+
+```python
+import msastats
+
+def stats_dict(msa):
+    return dict(zip(msastats.stats_names(), msastats.calculate_msa_stats(msa)))
+```
+
+#### Example 1: One gap interval shared by 2 of 3 sequences
+
+```python
+msa = ["A--A", "A--A", "AAAA"]  # N=3, L=4
+stats = stats_dict(msa)
+
+assert stats["MSA_LEN"] == 4.0
+assert stats["LONGEST_UNALIGNED_SEQ"] == 4.0
+assert stats["SHORTEST_UNALIGNED_SEQ"] == 2.0
+
+# One unique gap interval of length 2, appearing in 2 sequences:
+assert stats["TOT_NUM_UNIQUE_GAPS"] == 1.0
+assert stats["TOT_NUM_GAPS"] == 2.0
+assert stats["AVG_GAP_SIZE"] == 2.0
+assert stats["NUM_GAPS_LEN_TWO"] == 2.0
+
+# Column-wise gap counts (original alignment):
+assert stats["MSA_POSITION_WITH_0_GAPS"] == 2.0
+assert stats["MSA_POSITION_WITH_2_GAPS"] == 2.0
+```
+
+#### Example 2: All-gap columns are ignored for gap-run detection
+
+```python
+msa = ["A-A", "A-A", "A-A"]  # middle column is all gaps
+stats = stats_dict(msa)
+
+assert stats["MSA_LEN"] == 3.0
+
+# The all-gap column is removed before gap runs are detected, so there are no gaps:
+assert stats["TOT_NUM_GAPS"] == 0.0
+assert stats["TOT_NUM_UNIQUE_GAPS"] == 0.0
+assert stats["AVG_GAP_SIZE"] == 0.0
+
+# But column-wise counts still “see” the original alignment columns:
+assert stats["MSA_POSITION_WITH_0_GAPS"] == 2.0
+```
+
+#### Example 3: “total gap runs” vs “unique gap intervals”
+
+```python
+msa = ["A-A", "A-A", "AAA", "AAA"]  # one gap interval shared by 2 sequences
+stats = stats_dict(msa)
+
+# Total occurrences (one per sequence that has it):
+assert stats["NUM_GAPS_LEN_ONE"] == 2.0
+
+# Unique intervals are counted once:
+assert stats["TOT_NUM_UNIQUE_GAPS"] == 1.0
+assert stats["NUM_GAPS_LEN_ONE_IN_TWO_SEQS"] == 1.0
+```

pymsastats-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+msa_stats_calculator.py,sha256=vh4ykrP8pK1fF-czYG04S5XezIBbLIofhIkZpCmBcgM,20912
+msastats.py,sha256=4mteH4JbIPgxSkBkiGIE1VhS6lsv44SF6DwZ68wC9vA,1488
+pymsastats-0.1.0.dist-info/licenses/LICENSE,sha256=huhwDNhNzr24NkyPX5pH_F4BiS_cYVrZwyXB_ZynjqE,1071
+pymsastats-0.1.0.dist-info/METADATA,sha256=sT7hWXuBoctX715iU1PZYFRqNarbD9sH0DtU1skXT1g,11526
+pymsastats-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+pymsastats-0.1.0.dist-info/top_level.txt,sha256=Per3ZNEbyffbfTUtyfzXEWzt6eT2PBORZ2Mp8QrLoEQ,30
+pymsastats-0.1.0.dist-info/RECORD,,

pymsastats-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pymsastats-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Naiel Jabareen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pymsastats-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+msa_stats_calculator
+msastats