pylocuszoom 0.6.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

pylocuszoom/gene_track.py

@@ -28,6 +28,10 @@ GENE_AREA = 0.25  # Bottom portion for gene drawing
 EXON_HEIGHT = 0.20  # Exon rectangle height
 INTRON_HEIGHT = 0.02  # Thin intron line
 
+# Arrow dimensions (pre-computed for clarity)
+ARROW_HEIGHT_RATIO = 0.2625  # EXON_HEIGHT * 0.35 * 0.75 (75% of original height)
+ARROW_WIDTH_RATIO = 0.0066  # region_width * 0.006 * 1.1 (10% wider than original)
+
 
 def assign_gene_positions(genes_df: pd.DataFrame, start: int, end: int) -> List[int]:
     """Assign row indices to genes to minimize overlap.
@@ -44,22 +48,23 @@ def assign_gene_positions(genes_df: pd.DataFrame, start: int, end: int) -> List[
         List of integer row indices (0, 1, 2, ...) for each gene.
     """
     positions = []
-    occupied = []  # List of (end_pos, row)
+    # Track the rightmost end position for each row (including label buffer)
+    row_ends: dict[int, int] = {}  # row -> rightmost end position
     region_width = end - start
+    label_buffer = region_width * 0.08  # Extra space for labels
 
     for _, gene in genes_df.iterrows():
         gene_start = max(gene["start"], start)
         gene_end = min(gene["end"], end)
 
-        # Find first available row with buffer for label spacing
+        # Find first available row where gene doesn't overlap
         row = 0
-        label_buffer = region_width * 0.08  # Extra space for labels
-        for occ_end, occ_row in occupied:
-            if occ_row == row and occ_end > gene_start - label_buffer:
-                row = occ_row + 1
+        while row in row_ends and row_ends[row] > gene_start - label_buffer:
+            row += 1
 
         positions.append(row)
-        occupied.append((gene_end, row))
+        # Update the row's end position (including buffer for next gene check)
+        row_ends[row] = gene_end
 
     return positions
 
@@ -111,6 +116,147 @@ def get_nearest_gene(
     return nearby.loc[nearby["dist"].idxmin(), "gene_name"]
 
 
+def _filter_genes_by_region(
+    df: pd.DataFrame, chrom: Union[int, str], start: int, end: int
+) -> pd.DataFrame:
+    """Filter a DataFrame to genes/exons within a genomic region."""
+    chrom_str = normalize_chrom(chrom)
+    return df[
+        (df["chr"].astype(str).str.replace("chr", "", regex=False) == chrom_str)
+        & (df["end"] >= start)
+        & (df["start"] <= end)
+    ].copy()
+
+
+def _compute_arrow_geometry(
+    gene_start: int, gene_end: int, region_width: int, strand: str
+) -> tuple[list[float], float, float, str]:
+    """Compute arrow tip positions and dimensions for strand arrows.
+
+    Returns:
+        Tuple of (arrow_tip_positions, tri_height, tri_width, arrow_color).
+    """
+    tri_height = EXON_HEIGHT * ARROW_HEIGHT_RATIO
+    tri_width = region_width * ARROW_WIDTH_RATIO
+
+    tip_offset = tri_width / 2
+    tail_offset = tri_width * 1.5
+    gene_center = (gene_start + gene_end) / 2
+
+    if strand == "+":
+        arrow_tip_positions = [
+            gene_start + tail_offset,
+            gene_center + tri_width / 2,
+            gene_end - tip_offset,
+        ]
+        arrow_color = "#000000"
+    else:
+        arrow_tip_positions = [
+            gene_end - tail_offset,
+            gene_center - tri_width / 2,
+            gene_start + tip_offset,
+        ]
+        arrow_color = "#333333"
+
+    return arrow_tip_positions, tri_height, tri_width, arrow_color
+
+
+def _draw_strand_arrows_matplotlib(
+    ax: Axes,
+    gene: pd.Series,
+    gene_start: int,
+    gene_end: int,
+    y_gene: float,
+    region_width: int,
+) -> None:
+    """Draw strand direction arrows using matplotlib."""
+    strand = gene["strand"]
+    arrow_tip_positions, tri_height, tri_width, arrow_color = _compute_arrow_geometry(
+        gene_start, gene_end, region_width, strand
+    )
+
+    # Draw connecting line between arrow centers
+    if len(arrow_tip_positions) > 1:
+        ax.plot(
+            [arrow_tip_positions[0], arrow_tip_positions[-1]],
+            [y_gene, y_gene],
+            color=arrow_color,
+            linewidth=1.0,
+            zorder=4,
+            solid_capstyle="butt",
+        )
+
+    for tip_x in arrow_tip_positions:
+        if strand == "+":
+            base_x = tip_x - tri_width
+        else:
+            base_x = tip_x + tri_width
+
+        tri_points = [
+            [tip_x, y_gene],
+            [base_x, y_gene + tri_height],
+            [base_x, y_gene - tri_height],
+        ]
+
+        triangle = Polygon(
+            tri_points,
+            closed=True,
+            facecolor=arrow_color,
+            edgecolor=arrow_color,
+            linewidth=0.5,
+            zorder=5,
+        )
+        ax.add_patch(triangle)
+
+
+def _draw_strand_arrows_generic(
+    ax: Any,
+    backend: Any,
+    gene: pd.Series,
+    gene_start: int,
+    gene_end: int,
+    y_gene: float,
+    region_width: int,
+) -> None:
+    """Draw strand direction arrows using a generic backend."""
+    strand = gene["strand"]
+    arrow_tip_positions, tri_height, tri_width, arrow_color = _compute_arrow_geometry(
+        gene_start, gene_end, region_width, strand
+    )
+
+    # Draw connecting line between arrow centers
+    if len(arrow_tip_positions) > 1:
+        backend.line(
+            ax,
+            x=pd.Series([arrow_tip_positions[0], arrow_tip_positions[-1]]),
+            y=pd.Series([y_gene, y_gene]),
+            color=arrow_color,
+            linewidth=1.0,
+            zorder=4,
+        )
+
+    for tip_x in arrow_tip_positions:
+        if strand == "+":
+            base_x = tip_x - tri_width
+        else:
+            base_x = tip_x + tri_width
+
+        tri_points = [
+            [tip_x, y_gene],
+            [base_x, y_gene + tri_height],
+            [base_x, y_gene - tri_height],
+        ]
+
+        backend.add_polygon(
+            ax,
+            tri_points,
+            facecolor=arrow_color,
+            edgecolor=arrow_color,
+            linewidth=0.5,
+            zorder=5,
+        )
+
+
 def plot_gene_track(
     ax: Axes,
     genes_df: pd.DataFrame,
@@ -137,12 +283,7 @@ def plot_gene_track(
         exons_df: Exon annotations with chr, start, end, gene_name
             columns for drawing exon structure. Optional.
     """
-    chrom_str = normalize_chrom(chrom)
-    region_genes = genes_df[
-        (genes_df["chr"].astype(str).str.replace("chr", "", regex=False) == chrom_str)
-        & (genes_df["end"] >= start)
-        & (genes_df["start"] <= end)
-    ].copy()
+    region_genes = _filter_genes_by_region(genes_df, chrom, start, end)
 
     ax.set_xlim(start, end)
     ax.set_ylabel("")
@@ -178,20 +319,13 @@ def plot_gene_track(
     top_margin = 0.05  # Minimal space above top label
     ax.set_ylim(
         -bottom_margin,
-        (max_row + 1) * ROW_HEIGHT - ROW_HEIGHT + GENE_AREA + top_margin,
+        max_row * ROW_HEIGHT + GENE_AREA + top_margin,
     )
 
     # Filter exons for this region if available
     region_exons = None
     if exons_df is not None and not exons_df.empty:
-        region_exons = exons_df[
-            (
-                exons_df["chr"].astype(str).str.replace("chr", "", regex=False)
-                == chrom_str
-            )
-            & (exons_df["end"] >= start)
-            & (exons_df["start"] <= end)
-        ].copy()
+        region_exons = _filter_genes_by_region(exons_df, chrom, start, end)
 
     region_width = end - start
 
@@ -257,59 +391,11 @@ def plot_gene_track(
                 )
             )
 
-        # Add strand direction triangles (tip, center, tail)
+        # Add strand direction triangles
         if "strand" in gene.index:
-            strand = gene["strand"]
-            arrow_dir = 1 if strand == "+" else -1
-
-            # Triangle dimensions
-            tri_height = EXON_HEIGHT * 0.35
-            tri_width = region_width * 0.006
-
-            # Arrow positions: front, middle, back (tip positions)
-            tip_offset = tri_width / 2  # Tiny offset to keep tip inside gene
-            tail_offset = tri_width * 1.5  # Offset for tail arrow from gene start/end
-            gene_center = (gene_start + gene_end) / 2
-            if arrow_dir == 1:  # Forward strand
-                arrow_tip_positions = [
-                    gene_start + tail_offset,  # Tail (tip inside gene)
-                    gene_center + tri_width / 2,  # Middle (arrow center at gene center)
-                    gene_end - tip_offset,  # Tip (near gene end)
-                ]
-                arrow_color = "#000000"  # Black for forward
-            else:  # Reverse strand
-                arrow_tip_positions = [
-                    gene_end - tail_offset,  # Tail (tip inside gene)
-                    gene_center - tri_width / 2,  # Middle (arrow center at gene center)
-                    gene_start + tip_offset,  # Tip (near gene start)
-                ]
-                arrow_color = "#333333"  # Dark grey for reverse
-
-            for tip_x in arrow_tip_positions:
-                if arrow_dir == 1:
-                    base_x = tip_x - tri_width
-                    tri_points = [
-                        [tip_x, y_gene],  # Tip pointing right
-                        [base_x, y_gene + tri_height],
-                        [base_x, y_gene - tri_height],
-                    ]
-                else:
-                    base_x = tip_x + tri_width
-                    tri_points = [
-                        [tip_x, y_gene],  # Tip pointing left
-                        [base_x, y_gene + tri_height],
-                        [base_x, y_gene - tri_height],
-                    ]
-
-                triangle = Polygon(
-                    tri_points,
-                    closed=True,
-                    facecolor=arrow_color,
-                    edgecolor=arrow_color,
-                    linewidth=0.5,
-                    zorder=5,
-                )
-                ax.add_patch(triangle)
+            _draw_strand_arrows_matplotlib(
+                ax, gene, gene_start, gene_end, y_gene, region_width
+            )
 
         # Add gene name label in the gap above gene
         if gene_name:
@@ -320,7 +406,7 @@ def plot_gene_track(
                 gene_name,
                 ha="center",
                 va="bottom",
-                fontsize=5.5,
+                fontsize=7,
                 color="#000000",
                 fontweight="medium",
                 style="italic",
@@ -353,12 +439,7 @@ def plot_gene_track_generic(
         exons_df: Exon annotations with chr, start, end, gene_name
             columns for drawing exon structure. Optional.
     """
-    chrom_str = normalize_chrom(chrom)
-    region_genes = genes_df[
-        (genes_df["chr"].astype(str).str.replace("chr", "", regex=False) == chrom_str)
-        & (genes_df["end"] >= start)
-        & (genes_df["start"] <= end)
-    ].copy()
+    region_genes = _filter_genes_by_region(genes_df, chrom, start, end)
 
     backend.set_xlim(ax, start, end)
     backend.set_ylabel(ax, "", fontsize=10)
@@ -389,20 +470,13 @@ def plot_gene_track_generic(
     backend.set_ylim(
         ax,
         -bottom_margin,
-        (max_row + 1) * ROW_HEIGHT - ROW_HEIGHT + GENE_AREA + top_margin,
+        max_row * ROW_HEIGHT + GENE_AREA + top_margin,
     )
 
     # Filter exons for this region if available
     region_exons = None
     if exons_df is not None and not exons_df.empty:
-        region_exons = exons_df[
-            (
-                exons_df["chr"].astype(str).str.replace("chr", "", regex=False)
-                == chrom_str
-            )
-            & (exons_df["end"] >= start)
-            & (exons_df["start"] <= end)
-        ].copy()
+        region_exons = _filter_genes_by_region(exons_df, chrom, start, end)
 
     region_width = end - start
 
@@ -465,58 +539,11 @@ def plot_gene_track_generic(
                 zorder=2,
             )
 
-        # Add strand direction triangles (tip, center, tail)
+        # Add strand direction triangles
         if "strand" in gene.index:
-            strand = gene["strand"]
-            arrow_dir = 1 if strand == "+" else -1
-
-            # Triangle dimensions
-            tri_height = EXON_HEIGHT * 0.35
-            tri_width = region_width * 0.006
-
-            # Arrow positions: front, middle, back (tip positions)
-            tip_offset = tri_width / 2  # Tiny offset to keep tip inside gene
-            tail_offset = tri_width * 1.5  # Offset for tail arrow from gene start/end
-            gene_center = (gene_start + gene_end) / 2
-            if arrow_dir == 1:  # Forward strand
-                arrow_tip_positions = [
-                    gene_start + tail_offset,  # Tail (tip inside gene)
-                    gene_center + tri_width / 2,  # Middle (arrow center at gene center)
-                    gene_end - tip_offset,  # Tip (near gene end)
-                ]
-                arrow_color = "#000000"  # Black for forward
-            else:  # Reverse strand
-                arrow_tip_positions = [
-                    gene_end - tail_offset,  # Tail (tip inside gene)
-                    gene_center - tri_width / 2,  # Middle (arrow center at gene center)
-                    gene_start + tip_offset,  # Tip (near gene start)
-                ]
-                arrow_color = "#333333"  # Dark grey for reverse
-
-            for tip_x in arrow_tip_positions:
-                if arrow_dir == 1:
-                    base_x = tip_x - tri_width
-                    tri_points = [
-                        [tip_x, y_gene],  # Tip pointing right
-                        [base_x, y_gene + tri_height],
-                        [base_x, y_gene - tri_height],
-                    ]
-                else:
-                    base_x = tip_x + tri_width
-                    tri_points = [
-                        [tip_x, y_gene],  # Tip pointing left
-                        [base_x, y_gene + tri_height],
-                        [base_x, y_gene - tri_height],
-                    ]
-
-                backend.add_polygon(
-                    ax,
-                    tri_points,
-                    facecolor=arrow_color,
-                    edgecolor=arrow_color,
-                    linewidth=0.5,
-                    zorder=5,
-                )
+            _draw_strand_arrows_generic(
+                ax, backend, gene, gene_start, gene_end, y_gene, region_width
+            )
 
         # Add gene name label in the gap above gene
         if gene_name:
@@ -526,7 +553,7 @@ def plot_gene_track_generic(
                 label_pos,
                 y_label,
                 gene_name,
-                fontsize=6,
+                fontsize=7,
                 ha="center",
                 va="bottom",
                 color="#000000",

pylocuszoom/loaders.py

@@ -877,4 +877,6 @@ def load_gwas(
     if format not in loaders:
         raise ValueError(f"Unknown format '{format}'. Options: {list(loaders.keys())}")
 
-    return loaders[format](filepath, pos_col=pos_col, p_col=p_col, rs_col=rs_col)
+    return loaders[format](
+        filepath, pos_col=pos_col, p_col=p_col, rs_col=rs_col, **kwargs
+    )

pylocuszoom/phewas.py

@@ -5,7 +5,7 @@ Validates and prepares phenome-wide association study data for plotting.
 
 import pandas as pd
 
-from .utils import ValidationError
+from .validation import DataFrameValidator
 
 
 def validate_phewas_df(
@@ -14,7 +14,7 @@ def validate_phewas_df(
     p_col: str = "p_value",
     category_col: str = "category",
 ) -> None:
-    """Validate PheWAS DataFrame has required columns.
+    """Validate PheWAS DataFrame has required columns and types.
 
     Args:
         df: PheWAS results DataFrame.
@@ -23,13 +23,12 @@ def validate_phewas_df(
         category_col: Column name for phenotype categories (optional).
 
     Raises:
-        ValidationError: If required columns are missing.
+        ValidationError: If required columns are missing or have invalid types.
     """
-    required = [phenotype_col, p_col]
-    missing = [col for col in required if col not in df.columns]
-
-    if missing:
-        raise ValidationError(
-            f"PheWAS DataFrame missing required columns: {missing}. "
-            f"Required: {required}. Found: {list(df.columns)}"
-        )
+    (
+        DataFrameValidator(df, "PheWAS DataFrame")
+        .require_columns([phenotype_col, p_col])
+        .require_numeric([p_col])
+        .require_range(p_col, min_val=0, max_val=1, exclusive_min=True)
+        .validate()
+    )