cooper-beta 0.1.0__py3-none-any.whl

cooper_beta/__init__.py

@@ -0,0 +1,66 @@
+"""
+cooper_beta
+
+A small toolkit/pipeline to detect beta-barrel-like protein chains from PDB/mmCIF structures.
+"""
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("cooper-beta")
+except PackageNotFoundError:  # pragma: no cover - editable tree before metadata exists
+    __version__ = "0.0.0"
+
+__all__ = [
+    "AppConfig",
+    "AnalysisReport",
+    "Config",
+    "ConfigValidationError",
+    "ChainNotFoundError",
+    "CooperBetaError",
+    "DetectionResult",
+    "DsspError",
+    "DsspNotFoundError",
+    "InputValidationError",
+    "LayerDiagnostic",
+    "PipelineRunResult",
+    "PreparedChainPayload",
+    "ProteinLoader",
+    "PCAAligner",
+    "ProteinSlicer",
+    "ResidueRecord",
+    "StructureParseError",
+    "BarrelAnalyzer",
+    "build_config",
+    "detect",
+    "find_dssp_binary",
+    "require_dssp_binary",
+    "main",
+    "__version__",
+]
+
+from .alignment import PCAAligner
+from .analyzer import BarrelAnalyzer
+from .config import AppConfig, Config, build_config
+from .exceptions import (
+    ChainNotFoundError,
+    ConfigValidationError,
+    CooperBetaError,
+    DsspError,
+    DsspNotFoundError,
+    InputValidationError,
+    StructureParseError,
+)
+from .loader import ProteinLoader
+from .models import (
+    AnalysisReport,
+    DetectionResult,
+    LayerDiagnostic,
+    PipelineRunResult,
+    PreparedChainPayload,
+    ResidueRecord,
+)
+from .pipeline import detect, main
+from .runtime import find_dssp_binary, require_dssp_binary
+from .slicer import ProteinSlicer

cooper_beta/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

cooper_beta/alignment.py

@@ -0,0 +1,75 @@
+import numpy as np
+
+
+class PCAAligner:
+    """
+    Use PCA to align the principal axis of a point cloud to the Z axis.
+    """
+    def __init__(self):
+        self.center = None
+        self.rotation_matrix = None
+        self.eigenvalues = None
+
+    def fit(self, points):
+        """
+        Compute the principal axes of the point cloud.
+
+        For best results, pass only C-alpha coordinates from beta-sheet residues.
+
+        Args:
+            points (np.ndarray): Coordinate array with shape ``(N, 3)``.
+        """
+        coords = np.array(points)
+        if coords.shape[0] < 3:
+            raise ValueError("At least three points are required for PCA alignment.")
+
+        # 1. Compute the centroid and center the coordinates.
+        self.center = np.mean(coords, axis=0)
+        centered_coords = coords - self.center
+
+        # 2. Build the covariance matrix.
+        # rowvar=False means columns are variables (x, y, z) and rows are samples.
+        cov_matrix = np.cov(centered_coords, rowvar=False)
+
+        # 3. Eigen decomposition.
+        # eigh is appropriate for symmetric matrices such as covariance matrices,
+        # and is usually more stable than eig here.
+        # eig_vals are returned in ascending order (min -> max), and each column
+        # of eig_vecs is a corresponding eigenvector.
+        eig_vals, eig_vecs = np.linalg.eigh(cov_matrix)
+
+        self.eigenvalues = eig_vals
+        self.rotation_matrix = eig_vecs
+        
+        # Debug helper: variance contribution of each PCA axis.
+        # variance_ratio = eig_vals / np.sum(eig_vals)
+        # print(f"PCA Variance Ratios (X, Y, Z): {variance_ratio}")
+
+    def transform(self, points):
+        """
+        Project the point cloud into the PCA coordinate system.
+
+        After transformation, the Z axis corresponds to the dominant principal
+        axis of the original point cloud.
+        """
+        if self.rotation_matrix is None:
+            raise RuntimeError("Aligner is not fitted. Call fit() first.")
+
+        coords = np.array(points)
+
+        # 1. Translate to the centered coordinate system.
+        centered = coords - self.center
+
+        # 2. Rotate by projecting onto the eigenvector basis.
+        # result = centered @ eigenvectors
+        # Column 0 corresponds to the smallest eigenvalue direction (new X),
+        # column 1 to the middle eigenvalue direction (new Y), and column 2 to
+        # the largest eigenvalue direction (new Z, the principal axis).
+        transformed = np.dot(centered, self.rotation_matrix)
+
+        return transformed
+
+    def fit_transform(self, points):
+        """Convenience wrapper that runs ``fit`` followed by ``transform``."""
+        self.fit(points)
+        return self.transform(points)

cooper_beta/analysis_utils.py

@@ -0,0 +1,254 @@
+from __future__ import annotations
+
+import numpy as np
+from scipy.spatial import cKDTree
+
+from .config import AngleOrderRuleConfig
+from .constants import (
+    EPSILON,
+    FULL_ROTATION_DEG,
+    MIN_ANGULAR_GAP_POINTS,
+    MIN_NEAREST_NEIGHBOR_POINTS,
+    MIN_SEQUENCE_ANGLE_ORDER_POINTS,
+    RAD_TO_DEG,
+    ROBUST_SIGMA_SCALE,
+    THREE_SIGMA_MULTIPLIER,
+    TOLERANCE,
+)
+
+
+def robust_center(points_xy: np.ndarray) -> tuple[float, float]:
+    """Return the mean center of a slice cross section."""
+    pts = np.asarray(points_xy, dtype=float)
+    center = np.mean(pts, axis=0)
+    return float(center[0]), float(center[1])
+
+
+def radial_inlier_subset(
+    points_xy: np.ndarray,
+    *,
+    minimum_points: int,
+) -> tuple[np.ndarray, np.ndarray, float, float] | None:
+    """
+    Filter radial outliers and return the filtered points with a recentered origin.
+
+    The initial center is used only to identify gross radial outliers. Once those
+    points are removed, the center is recomputed on the retained subset so filtered
+    points do not keep biasing downstream angular statistics.
+    """
+    pts = np.asarray(points_xy, dtype=float)
+    if pts.ndim != 2 or pts.shape[0] < minimum_points:
+        return None
+
+    initial_center_x, initial_center_y = robust_center(pts)
+    delta_x = pts[:, 0] - initial_center_x
+    delta_y = pts[:, 1] - initial_center_y
+    radius = np.sqrt(delta_x * delta_x + delta_y * delta_y)
+
+    median_radius = float(np.median(radius))
+    mad_radius = float(np.median(np.abs(radius - median_radius)))
+    radius_sigma = float(ROBUST_SIGMA_SCALE * mad_radius)
+
+    if radius_sigma > TOLERANCE:
+        keep_mask = np.abs(radius - median_radius) <= (THREE_SIGMA_MULTIPLIER * radius_sigma)
+        filtered_points = pts[keep_mask]
+    else:
+        keep_mask = np.ones(pts.shape[0], dtype=bool)
+        filtered_points = pts
+
+    if filtered_points.shape[0] < minimum_points:
+        return None
+
+    center_x, center_y = robust_center(filtered_points)
+    return filtered_points, keep_mask, center_x, center_y
+
+
+def collapse_points_by_strand(points: np.ndarray) -> np.ndarray:
+    """
+    Collapse multiple same-strand intersections within one slice to one point.
+
+    When a strand contributes more than one segment-plane intersection, we compare
+    barrel order at the strand level instead of the raw segment level. This keeps
+    ``seq_order`` closer to the scientific notion of strand order around the barrel.
+    """
+    pts = np.asarray(points, dtype=float)
+    if pts.ndim != 2 or pts.shape[1] < 4:
+        return pts
+
+    strand_ids = pts[:, 3].astype(int)
+    unique_strands = np.unique(strand_ids)
+    if unique_strands.size == pts.shape[0]:
+        return pts
+
+    collapsed = np.empty((unique_strands.size, 4), dtype=float)
+    for index, strand_id in enumerate(unique_strands):
+        strand_points = pts[strand_ids == strand_id]
+        collapsed[index, :2] = np.mean(strand_points[:, :2], axis=0)
+        collapsed[index, 2] = float(np.median(strand_points[:, 2]))
+        collapsed[index, 3] = float(strand_id)
+    return collapsed
+
+
+def nearest_neighbor_spacing_stats(
+    points_xy: np.ndarray,
+) -> tuple[float, float, float, float] | None:
+    """Return robust nearest-neighbor spacing statistics for one slice."""
+    pts = np.asarray(points_xy, dtype=float)
+    if pts.ndim != 2 or pts.shape[0] < MIN_NEAREST_NEIGHBOR_POINTS:
+        return None
+
+    tree = cKDTree(pts)
+    distances, _ = tree.query(pts, k=2)
+    nearest_neighbor = distances[:, 1]
+
+    median_distance = float(np.median(nearest_neighbor))
+    mad_distance = float(np.median(np.abs(nearest_neighbor - median_distance)))
+    robust_sigma = float(ROBUST_SIGMA_SCALE * mad_distance)
+
+    if median_distance <= TOLERANCE:
+        robust_cv = float("inf")
+    else:
+        robust_cv = float(robust_sigma / median_distance)
+
+    if robust_sigma < EPSILON:
+        return median_distance, 0.0, 0.0, 1.0
+
+    inliers = np.abs(nearest_neighbor - median_distance) <= (
+        THREE_SIGMA_MULTIPLIER * robust_sigma
+    )
+    inlier_fraction = float(np.mean(inliers)) if len(inliers) else 0.0
+    return median_distance, robust_sigma, robust_cv, inlier_fraction
+
+
+def angular_gap_stats(
+    points_xy: np.ndarray,
+) -> tuple[float, float, int, float, float] | None:
+    """Return max angular gap, coverage, used count, and center coordinates."""
+    filtered = radial_inlier_subset(points_xy, minimum_points=MIN_ANGULAR_GAP_POINTS)
+    if filtered is None:
+        return None
+    filtered_points, _, center_x, center_y = filtered
+
+    filtered_dx = filtered_points[:, 0] - center_x
+    filtered_dy = filtered_points[:, 1] - center_y
+    angle = np.sort(np.arctan2(filtered_dy, filtered_dx))
+
+    differences = np.diff(angle)
+    wrap_difference = (angle[0] + (2.0 * np.pi)) - angle[-1]
+    circular_differences = np.concatenate([differences, [wrap_difference]])
+
+    max_gap_radians = float(np.max(circular_differences))
+    max_gap_degrees = max_gap_radians * RAD_TO_DEG
+    coverage_degrees = FULL_ROTATION_DEG - max_gap_degrees
+
+    return (
+        max_gap_degrees,
+        coverage_degrees,
+        int(filtered_points.shape[0]),
+        center_x,
+        center_y,
+    )
+
+
+def best_circular_affine_fit_cost(angle_pos_by_seq: np.ndarray) -> float:
+    """Return normalized sequence/angle-order mismatch under shift and reversal."""
+    positions = np.asarray(angle_pos_by_seq, dtype=int)
+    count = int(positions.size)
+    if count <= 1:
+        return 0.0
+
+    normalization = max(1.0, count / 2.0)
+    best_cost = float("inf")
+
+    base_order = np.arange(count, dtype=int)
+    for direction in (1, -1):
+        directed_order = (direction * base_order) % count
+        for shift in range(count):
+            predicted = (directed_order + shift) % count
+            distance = np.abs(positions - predicted)
+            distance = np.minimum(distance, count - distance)
+            candidate_cost = float(np.mean(distance)) / normalization
+            if candidate_cost < best_cost:
+                best_cost = candidate_cost
+
+    return float(min(1.0, max(0.0, best_cost)))
+
+
+def sequence_angle_order_stats(
+    points: np.ndarray,
+    order_config: AngleOrderRuleConfig,
+) -> dict[str, float | int] | None:
+    """Compute sequence-order versus angle-order consistency on one slice."""
+    pts = collapse_points_by_strand(np.asarray(points, dtype=float))
+    if pts.ndim == 2 and pts.shape[1] >= 4:
+        pts = pts[:, :3]
+    if (
+        pts.ndim != 2
+        or pts.shape[0] < MIN_SEQUENCE_ANGLE_ORDER_POINTS
+        or pts.shape[1] < 3
+    ):
+        return None
+
+    filtered = radial_inlier_subset(pts[:, :2], minimum_points=MIN_SEQUENCE_ANGLE_ORDER_POINTS)
+    if filtered is None:
+        return None
+    filtered_xy, keep_mask, center_x, center_y = filtered
+
+    filtered_sequence_position = pts[keep_mask, 2]
+    count = int(filtered_xy.shape[0])
+
+    sequence_order = np.argsort(filtered_sequence_position, kind="mergesort")
+    filtered_dx = filtered_xy[:, 0] - center_x
+    filtered_dy = filtered_xy[:, 1] - center_y
+    angle = (np.arctan2(filtered_dy, filtered_dx) * RAD_TO_DEG) % FULL_ROTATION_DEG
+    angle_order = np.argsort(angle, kind="mergesort")
+
+    position_in_angle_order = np.empty(count, dtype=int)
+    position_in_angle_order[angle_order] = np.arange(count, dtype=int)
+    angle_position_by_sequence = position_in_angle_order[sequence_order]
+
+    local_steps = []
+    for index in range(count - 1):
+        step = abs(
+            int(angle_position_by_sequence[index + 1]) - int(angle_position_by_sequence[index])
+        )
+        local_steps.append(min(step, count - step))
+    local_steps_array = np.asarray(local_steps, dtype=float)
+
+    local_fraction = (
+        float(np.mean(local_steps_array <= float(order_config.local_step_max)))
+        if local_steps_array.size
+        else 1.0
+    )
+    mean_step = float(np.mean(local_steps_array)) if local_steps_array.size else 0.0
+    max_step = float(np.max(local_steps_array)) if local_steps_array.size else 0.0
+
+    mean_circular_distance = float(best_circular_affine_fit_cost(angle_position_by_sequence))
+
+    sequence_order_xy = filtered_xy[sequence_order]
+    euclidean_steps = np.diff(sequence_order_xy, axis=0)
+    sequence_neighbor_distance = np.sqrt(np.sum(euclidean_steps * euclidean_steps, axis=1))
+    if sequence_neighbor_distance.size:
+        median_neighbor_distance = float(np.median(sequence_neighbor_distance))
+        mad_neighbor_distance = float(
+            np.median(np.abs(sequence_neighbor_distance - median_neighbor_distance))
+        )
+        robust_sigma = float(ROBUST_SIGMA_SCALE * mad_neighbor_distance)
+        robust_cv = (
+            float(robust_sigma / median_neighbor_distance)
+            if median_neighbor_distance > TOLERANCE
+            else float("inf")
+        )
+    else:
+        median_neighbor_distance = 0.0
+        robust_cv = 0.0
+
+    return {
+        "order_used_n": int(count),
+        "order_local_frac": float(local_fraction),
+        "order_mean_step": float(mean_step),
+        "order_max_step": float(max_step),
+        "order_mean_circ_dist_norm": float(mean_circular_distance),
+        "seq_neighbor_dist_median": float(median_neighbor_distance),
+        "seq_neighbor_dist_robust_cv": float(robust_cv),
+    }