phykit 2.1.0__py3-none-any.whl

phykit/__main__.py

@@ -0,0 +1,6 @@
+"""phykit.__main__: executed when phykit is called as script"""
+import sys
+
+from .phykit import Phykit
+
+Phykit()

phykit/helpers/boolean_argument_parsing.py

@@ -0,0 +1,12 @@
+import argparse
+
+
+def str2bool(v):
+    if isinstance(v, bool):
+        return v
+    if v.lower() in ("true", "t", "1"):
+        return True
+    elif v.lower() in ("false", "f", "0"):
+        return False
+    else:
+        raise argparse.ArgumentTypeError("Boolean value expected.")

phykit/helpers/caching.py

@@ -0,0 +1,201 @@
+"""
+Caching utilities for expensive computations
+"""
+
+import hashlib
+import pickle
+import os
+import tempfile
+from functools import wraps, lru_cache
+from typing import Any, Callable
+import json
+
+
+class ResultCache:
+    """
+    File-based cache for expensive computation results.
+    """
+
+    def __init__(self, cache_dir: str = None):
+        """
+        Initialize cache.
+
+        Args:
+            cache_dir: Directory for cache files (uses temp dir if None)
+        """
+        if cache_dir is None:
+            cache_dir = os.path.join(tempfile.gettempdir(), 'phykit_cache')
+
+        self.cache_dir = cache_dir
+        os.makedirs(self.cache_dir, exist_ok=True)
+
+    def _get_cache_key(self, *args, **kwargs) -> str:
+        """Generate a unique cache key from function arguments."""
+        # Create a string representation of arguments
+        key_parts = []
+
+        for arg in args:
+            if isinstance(arg, (str, int, float, bool)):
+                key_parts.append(str(arg))
+            elif hasattr(arg, '__dict__'):
+                # For objects, use their attributes
+                key_parts.append(json.dumps(vars(arg), sort_keys=True, default=str))
+            else:
+                key_parts.append(str(arg))
+
+        for k, v in sorted(kwargs.items()):
+            key_parts.append(f"{k}={v}")
+
+        key_string = "_".join(key_parts)
+        return hashlib.md5(key_string.encode()).hexdigest()
+
+    def get(self, cache_key: str) -> Any:
+        """Retrieve cached result."""
+        cache_file = os.path.join(self.cache_dir, f"{cache_key}.pkl")
+
+        if os.path.exists(cache_file):
+            try:
+                with open(cache_file, 'rb') as f:
+                    return pickle.load(f)
+            except:
+                # Cache corrupted, remove it
+                os.remove(cache_file)
+
+        return None
+
+    def set(self, cache_key: str, value: Any) -> None:
+        """Store result in cache."""
+        cache_file = os.path.join(self.cache_dir, f"{cache_key}.pkl")
+
+        try:
+            with open(cache_file, 'wb') as f:
+                pickle.dump(value, f)
+        except:
+            # Caching failed, continue without caching
+            pass
+
+    def clear(self) -> None:
+        """Clear all cached results."""
+        for file in os.listdir(self.cache_dir):
+            if file.endswith('.pkl'):
+                os.remove(os.path.join(self.cache_dir, file))
+
+
+def cached_computation(cache_instance: ResultCache = None):
+    """
+    Decorator for caching expensive computation results.
+
+    Usage:
+        @cached_computation()
+        def expensive_function(param1, param2):
+            # Expensive computation
+            return result
+    """
+    if cache_instance is None:
+        cache_instance = ResultCache()
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            # Generate cache key
+            cache_key = cache_instance._get_cache_key(func.__name__, *args, **kwargs)
+
+            # Try to get cached result
+            cached_result = cache_instance.get(cache_key)
+            if cached_result is not None:
+                return cached_result
+
+            # Compute result
+            result = func(*args, **kwargs)
+
+            # Cache result
+            cache_instance.set(cache_key, result)
+
+            return result
+
+        # Add method to clear cache for this function
+        wrapper.clear_cache = cache_instance.clear
+
+        return wrapper
+
+    return decorator
+
+
+# Specialized caching for tree operations
+@lru_cache(maxsize=128)
+def cached_tree_distance(tree_pickle: bytes, tip1: str, tip2: str) -> float:
+    """
+    Cache tree distance calculations.
+
+    Args:
+        tree_pickle: Pickled tree object
+        tip1: First tip name
+        tip2: Second tip name
+
+    Returns:
+        Distance between tips
+    """
+    import pickle
+    tree = pickle.loads(tree_pickle)
+    return tree.distance(tip1, tip2)
+
+
+# Specialized caching for alignment operations
+class AlignmentCache:
+    """
+    Specialized cache for alignment operations.
+    """
+
+    def __init__(self):
+        self._column_cache = {}
+        self._stats_cache = {}
+
+    @lru_cache(maxsize=1024)
+    def get_column(self, alignment_hash: str, column_idx: int) -> str:
+        """
+        Get cached alignment column.
+        """
+        return self._column_cache.get(f"{alignment_hash}_{column_idx}")
+
+    def set_column(self, alignment_hash: str, column_idx: int, column: str) -> None:
+        """
+        Cache alignment column.
+        """
+        self._column_cache[f"{alignment_hash}_{column_idx}"] = column
+
+    @lru_cache(maxsize=128)
+    def get_stats(self, alignment_hash: str, stat_type: str) -> Any:
+        """
+        Get cached alignment statistics.
+        """
+        return self._stats_cache.get(f"{alignment_hash}_{stat_type}")
+
+    def set_stats(self, alignment_hash: str, stat_type: str, stats: Any) -> None:
+        """
+        Cache alignment statistics.
+        """
+        self._stats_cache[f"{alignment_hash}_{stat_type}"] = stats
+
+    def clear(self) -> None:
+        """
+        Clear all caches.
+        """
+        self._column_cache.clear()
+        self._stats_cache.clear()
+        self.get_column.cache_clear()
+        self.get_stats.cache_clear()
+
+
+# Global cache instances
+_result_cache = ResultCache()
+_alignment_cache = AlignmentCache()
+
+
+def get_result_cache() -> ResultCache:
+    """Get global result cache instance."""
+    return _result_cache
+
+
+def get_alignment_cache() -> AlignmentCache:
+    """Get global alignment cache instance."""
+    return _alignment_cache

phykit/helpers/files.py

@@ -0,0 +1,125 @@
+from enum import Enum
+import sys
+from typing import Tuple, Optional
+from functools import lru_cache
+import hashlib
+import os
+
+from Bio import AlignIO
+from Bio.Align import MultipleSeqAlignment
+
+
+class FileFormat(Enum):
+    fasta = "fasta"
+    clustal = "clustal"
+    maf = "maf"
+    mauve = "mauve"
+    phylip = "phylip"
+    phylip_seq = "phylip-sequential"
+    phylip_rel = "phylip-relaxed"
+    stockholm = "stockholm"
+
+
+def _get_file_hash(file_path: str) -> str:
+    """Calculate a hash for file content to use as cache key."""
+    # Use file path, size, and modification time for cache key
+    # This is faster than hashing file contents
+    stat = os.stat(file_path)
+    cache_key = f"{file_path}_{stat.st_size}_{stat.st_mtime}"
+    return hashlib.md5(cache_key.encode()).hexdigest()
+
+def _detect_format_by_content(file_path: str) -> Optional[str]:
+    """Attempt to detect file format by examining file content."""
+    with open(file_path, 'r') as f:
+        first_line = f.readline().strip()
+
+        # Quick format detection based on first line
+        if first_line.startswith('>'):
+            return 'fasta'
+        elif first_line.startswith('CLUSTAL'):
+            return 'clustal'
+        elif first_line.startswith('#'):
+            # Could be Stockholm
+            if 'STOCKHOLM' in first_line:
+                return 'stockholm'
+        elif first_line.isdigit() or (len(first_line.split()) == 2 and
+                                      first_line.split()[0].isdigit()):
+            return 'phylip'
+
+    return None
+
+@lru_cache(maxsize=32)
+def _cached_alignment_read(file_hash: str, file_path: str, file_format: str) -> Tuple[MultipleSeqAlignment, bool]:
+    """Cached reading of alignment files."""
+    with open(file_path) as f:
+        alignment = AlignIO.read(f, file_format)
+    return alignment, is_protein_alignment(alignment)
+
+def get_alignment_and_format(
+    alignment_file_path: str
+) -> Tuple[MultipleSeqAlignment, str, bool]:
+    # Check if file exists first
+    if not os.path.exists(alignment_file_path):
+        print(f"{alignment_file_path} corresponds to no such file.")
+        print("Please check file name and pathing")
+        sys.exit(2)
+
+    # Try to detect format by content first
+    detected_format = _detect_format_by_content(alignment_file_path)
+
+    # Get file hash for caching
+    file_hash = _get_file_hash(alignment_file_path)
+
+    # If format was detected, try it first
+    if detected_format:
+        try:
+            alignment, is_protein = _cached_alignment_read(
+                file_hash, alignment_file_path, detected_format
+            )
+            return alignment, detected_format, is_protein
+        except (ValueError, AssertionError):
+            pass
+
+    # Fall back to trying all formats
+    for fileFormat in FileFormat:
+        # Skip the already tried format
+        if detected_format and fileFormat.value == detected_format:
+            continue
+
+        try:
+            alignment, is_protein = _cached_alignment_read(
+                file_hash, alignment_file_path, fileFormat.value
+            )
+            return alignment, fileFormat.value, is_protein
+        except (ValueError, AssertionError):
+            continue
+
+    # If we get here, no format worked
+    print(f"Could not determine format for {alignment_file_path}")
+    print("Please ensure the file is in a supported format")
+    sys.exit(2)
+
+
+def is_protein_alignment(alignment: MultipleSeqAlignment) -> bool:
+    nucleotide_set = {
+        "A", "C", "G", "T", "U", "-", "N", "?", "*"
+    }
+
+    for record in alignment:
+        seq_set = set(record.seq.upper())
+        if seq_set - nucleotide_set:
+            # if there are chars that are not in the nucl set,
+            # it's likely a protein sequence
+            return True
+
+    return False
+
+
+def read_single_column_file_to_list(single_col_file_path: str) -> list:
+    try:
+        with open(single_col_file_path) as f:
+            return [line.rstrip("\n").strip() for line in f]
+    except FileNotFoundError:
+        print(f"{single_col_file_path} corresponds to no such file or directory.")
+        print("Please check file name and pathing")
+        sys.exit(2)

phykit/helpers/parallel.py

@@ -0,0 +1,305 @@
+"""
+Parallel processing utilities for batch operations
+"""
+
+import multiprocessing as mp
+from functools import partial
+from typing import List, Any, Callable, Optional
+import numpy as np
+from concurrent.futures import ProcessPoolExecutor, ThreadPoolExecutor, as_completed
+import sys
+
+
+class ParallelProcessor:
+    """
+    Utility class for parallel processing of batch operations.
+    """
+
+    @staticmethod
+    def get_optimal_workers(data_size: int, min_chunk_size: int = 10) -> int:
+        """
+        Determine optimal number of workers based on data size.
+
+        Args:
+            data_size: Size of data to process
+            min_chunk_size: Minimum size per chunk
+
+        Returns:
+            Optimal number of workers
+        """
+        max_workers = mp.cpu_count()
+        optimal_workers = min(max_workers, max(1, data_size // min_chunk_size))
+        return min(optimal_workers, 8)  # Cap at 8 to avoid overhead
+
+    @staticmethod
+    def chunk_data(data: List[Any], num_chunks: int) -> List[List[Any]]:
+        """
+        Split data into chunks for parallel processing.
+
+        Args:
+            data: Data to split
+            num_chunks: Number of chunks
+
+        Returns:
+            List of data chunks
+        """
+        chunk_size = max(1, len(data) // num_chunks)
+        chunks = []
+
+        for i in range(0, len(data), chunk_size):
+            chunk = data[i:i + chunk_size]
+            if chunk:
+                chunks.append(chunk)
+
+        return chunks
+
+    @staticmethod
+    def parallel_map(
+        func: Callable,
+        data: List[Any],
+        num_workers: Optional[int] = None,
+        use_threads: bool = False,
+        show_progress: bool = False
+    ) -> List[Any]:
+        """
+        Apply function to data in parallel.
+
+        Args:
+            func: Function to apply
+            data: Data to process
+            num_workers: Number of workers (auto-determined if None)
+            use_threads: Use threads instead of processes
+            show_progress: Show progress bar
+
+        Returns:
+            List of results
+        """
+        if not data:
+            return []
+
+        # Determine number of workers
+        if num_workers is None:
+            num_workers = ParallelProcessor.get_optimal_workers(len(data))
+
+        # For small datasets, use sequential processing
+        if len(data) < 20 or num_workers == 1:
+            return [func(item) for item in data]
+
+        # Choose executor type
+        executor_class = ThreadPoolExecutor if use_threads else ProcessPoolExecutor
+
+        results = []
+        with executor_class(max_workers=num_workers) as executor:
+            if show_progress and sys.stderr.isatty():
+                try:
+                    from tqdm import tqdm
+                    futures = {executor.submit(func, item): i for i, item in enumerate(data)}
+                    results = [None] * len(data)
+
+                    for future in tqdm(as_completed(futures), total=len(data), desc="Processing"):
+                        idx = futures[future]
+                        results[idx] = future.result()
+                except ImportError:
+                    # Fallback without progress bar
+                    results = list(executor.map(func, data))
+            else:
+                results = list(executor.map(func, data))
+
+        return results
+
+    @staticmethod
+    def parallel_reduce(
+        func: Callable,
+        data: List[Any],
+        reduce_func: Callable,
+        initial_value: Any = None,
+        num_workers: Optional[int] = None
+    ) -> Any:
+        """
+        Apply function to data in parallel and reduce results.
+
+        Args:
+            func: Function to apply to each item
+            data: Data to process
+            reduce_func: Function to reduce results
+            initial_value: Initial value for reduction
+            num_workers: Number of workers
+
+        Returns:
+            Reduced result
+        """
+        # Apply function in parallel
+        results = ParallelProcessor.parallel_map(func, data, num_workers)
+
+        # Reduce results
+        if initial_value is not None:
+            result = initial_value
+            for item in results:
+                result = reduce_func(result, item)
+        else:
+            if not results:
+                return None
+            result = results[0]
+            for item in results[1:]:
+                result = reduce_func(result, item)
+
+        return result
+
+
+class BatchFileProcessor:
+    """
+    Process multiple files in parallel.
+    """
+
+    @staticmethod
+    def process_files(
+        file_paths: List[str],
+        processing_func: Callable,
+        num_workers: Optional[int] = None,
+        aggregate_func: Optional[Callable] = None
+    ) -> Any:
+        """
+        Process multiple files in parallel.
+
+        Args:
+            file_paths: List of file paths
+            processing_func: Function to process each file
+            num_workers: Number of workers
+            aggregate_func: Function to aggregate results
+
+        Returns:
+            Processed results or aggregated result
+        """
+        if not file_paths:
+            return []
+
+        # Process files in parallel
+        results = ParallelProcessor.parallel_map(
+            processing_func,
+            file_paths,
+            num_workers,
+            show_progress=True
+        )
+
+        # Aggregate results if function provided
+        if aggregate_func:
+            return aggregate_func(results)
+
+        return results
+
+    @staticmethod
+    def process_file_pairs(
+        file_pairs: List[Tuple[str, str]],
+        processing_func: Callable,
+        num_workers: Optional[int] = None
+    ) -> List[Any]:
+        """
+        Process pairs of files in parallel.
+
+        Args:
+            file_pairs: List of file path pairs
+            processing_func: Function to process each pair
+            num_workers: Number of workers
+
+        Returns:
+            List of results
+        """
+        def process_pair(pair):
+            return processing_func(pair[0], pair[1])
+
+        return ParallelProcessor.parallel_map(
+            process_pair,
+            file_pairs,
+            num_workers
+        )
+
+
+class NumpyParallel:
+    """
+    Utilities for parallel NumPy operations.
+    """
+
+    @staticmethod
+    def parallel_apply_along_axis(
+        func: Callable,
+        axis: int,
+        array: np.ndarray,
+        num_workers: Optional[int] = None
+    ) -> np.ndarray:
+        """
+        Apply function along axis in parallel.
+
+        Args:
+            func: Function to apply
+            axis: Axis along which to apply function
+            array: NumPy array
+            num_workers: Number of workers
+
+        Returns:
+            Result array
+        """
+        if axis == 0:
+            # Process columns
+            results = ParallelProcessor.parallel_map(
+                lambda col: func(array[:, col]),
+                list(range(array.shape[1])),
+                num_workers
+            )
+            return np.array(results).T
+        elif axis == 1:
+            # Process rows
+            results = ParallelProcessor.parallel_map(
+                lambda row: func(array[row, :]),
+                list(range(array.shape[0])),
+                num_workers
+            )
+            return np.array(results)
+        else:
+            raise ValueError(f"Unsupported axis: {axis}")
+
+    @staticmethod
+    def parallel_pairwise_operation(
+        items: List[Any],
+        operation_func: Callable,
+        num_workers: Optional[int] = None,
+        symmetric: bool = True
+    ) -> np.ndarray:
+        """
+        Perform pairwise operations in parallel.
+
+        Args:
+            items: List of items
+            operation_func: Function to apply to pairs
+            num_workers: Number of workers
+            symmetric: Whether operation is symmetric
+
+        Returns:
+            Matrix of pairwise results
+        """
+        n = len(items)
+        result_matrix = np.zeros((n, n))
+
+        # Generate pairs
+        pairs = []
+        for i in range(n):
+            for j in range(i + 1 if symmetric else 0, n):
+                pairs.append((i, j, items[i], items[j]))
+
+        # Process pairs in parallel
+        def process_pair(pair_data):
+            i, j, item1, item2 = pair_data
+            return i, j, operation_func(item1, item2)
+
+        results = ParallelProcessor.parallel_map(
+            process_pair,
+            pairs,
+            num_workers
+        )
+
+        # Fill result matrix
+        for i, j, value in results:
+            result_matrix[i, j] = value
+            if symmetric:
+                result_matrix[j, i] = value
+
+        return result_matrix