priorityx 0.1.1__py3-none-any.whl

priorityx/utils/helpers.py

@@ -0,0 +1,227 @@
+"""Display and summary utilities."""
+
+import pandas as pd
+
+
+def display_quadrant_summary(
+    results_df: pd.DataFrame,
+    entity_name: str = "Entity",
+    min_count: int = 10
+) -> None:
+    """
+    Print quadrant breakdown with counts and percentages.
+
+    Args:
+        results_df: Results from fit_priority_matrix()
+        entity_name: Name for entity type
+        min_count: Minimum count to include in summary (default: 10)
+
+    Examples:
+        >>> display_quadrant_summary(results_df, entity_name="Service")
+    """
+    # filter by minimum count if specified
+    if min_count > 0 and "count" in results_df.columns:
+        df = results_df[results_df["count"] >= min_count]
+    else:
+        df = results_df
+
+    print(f"\nQUADRANT ANALYSIS SUMMARY - {entity_name.upper()}S")
+
+    total_entities = len(df)
+
+    print(f"\nTotal {entity_name.lower()}s analyzed: {total_entities}")
+
+    if min_count > 0:
+        print(f"(Filtered to ≥{min_count} count)")
+
+    print("\nQuadrant Breakdown:")
+    print("-" * 40)
+
+    quadrant_order = ["Q1", "Q2", "Q3", "Q4"]
+    quadrant_labels = {
+        "Q1": "Q1 (Crisis - High volume, High growth)",
+        "Q2": "Q2 (Investigate - Low volume, High growth)",
+        "Q3": "Q3 (Monitor - Low volume, Low growth)",
+        "Q4": "Q4 (Low Priority - High volume, Low growth)",
+    }
+
+    for q in quadrant_order:
+        q_data = df[df["quadrant"] == q]
+        count = len(q_data)
+        pct = (count / total_entities * 100) if total_entities > 0 else 0
+
+        if count > 0:
+            print()
+            print(f"{quadrant_labels[q]}")
+            print(f"Count: {count} ({pct:.1f}%)")
+
+            # show top entities by count if available
+            if "count" in q_data.columns:
+                top_entities = q_data.nlargest(3, "count")
+                print("Top by volume:")
+                for _, row in top_entities.iterrows():
+                    entity_val = row.get("entity", row.get("Topic", "Unknown"))
+                    print(f"  {entity_val} ({int(row['count'])} count)")
+
+
+def display_transition_summary(
+    transitions_df: pd.DataFrame,
+    entity_name: str = "Entity"
+) -> None:
+    """
+    Print transition summary by risk level and type.
+
+    Args:
+        transitions_df: DataFrame from extract_transitions()
+        entity_name: Name for entity type
+
+    Examples:
+        >>> display_transition_summary(transitions_df, entity_name="Service")
+    """
+    if transitions_df.empty:
+        print(f"No transitions detected for {entity_name.lower()}s")
+        return
+
+    print(f"\nQUADRANT TRANSITION SUMMARY - {entity_name.upper()}S")
+
+    # group by risk level
+    risk_groups = transitions_df.groupby("risk_level")
+
+    for risk_level in ["critical", "high", "medium", "low"]:
+        if risk_level in risk_groups.groups:
+            group = risk_groups.get_group(risk_level)
+            print()
+            print(f"{risk_level.upper()} RISK TRANSITIONS ({len(group)} total):")
+            print("-" * 40)
+
+            # show up to 5 examples
+            for _, transition in group.head(5).iterrows():
+                print(f"{transition['entity']}")
+                print(
+                    f"  {transition['from_quadrant']} -> {transition['to_quadrant']} "
+                    f"({transition['transition_quarter']})"
+                )
+                print(f"  {transition['transition_type']}")
+                if 'volume_change' in transition:
+                    print(f"  Volume change: {transition['volume_change']:.3f}")
+                if 'growth_change' in transition:
+                    print(f"  Growth change: {transition['growth_change']:.3f}")
+                print()  # blank line between transitions
+
+            if len(group) > 5:
+                print(f"... and {len(group) - 5} more")
+
+
+def display_movement_summary(
+    movement_df: pd.DataFrame,
+    entity_name: str = "Entity"
+) -> None:
+    """
+    Print movement tracking summary.
+
+    Args:
+        movement_df: DataFrame from track_cumulative_movement()
+        entity_name: Name for entity type
+
+    Examples:
+        >>> display_movement_summary(movement_df, entity_name="Service")
+    """
+    if movement_df.empty:
+        print(f"No movement data for {entity_name.lower()}s")
+        return
+
+    print(f"\nCUMULATIVE MOVEMENT SUMMARY - {entity_name.upper()}S")
+
+    n_entities = movement_df["entity"].nunique()
+    n_periods = movement_df["quarter"].nunique()
+    n_observations = len(movement_df)
+
+    print(f"\nEntities tracked: {n_entities}")
+    print(f"Time periods: {n_periods}")
+    print(f"Total observations: {n_observations}")
+
+    # divergence analysis
+    if "quadrant_differs" in movement_df.columns:
+        divergences = movement_df["quadrant_differs"].sum()
+        div_pct = (divergences / n_observations * 100) if n_observations > 0 else 0
+        print(f"\nQuadrant divergences from global baseline: {divergences} ({div_pct:.1f}%)")
+        print("(Period quadrant != Global quadrant)")
+
+    # show entities with largest movements
+    if "x_delta" in movement_df.columns and "y_delta" in movement_df.columns:
+        entity_total_movement = movement_df.groupby("entity").agg({
+            "x_delta": lambda x: abs(x).sum(),
+            "y_delta": lambda x: abs(x).sum(),
+        })
+        entity_total_movement["total"] = (
+            entity_total_movement["x_delta"] + entity_total_movement["y_delta"]
+        )
+        top_movers = entity_total_movement.nlargest(5, "total")
+
+        print(f"\nTop {entity_name.lower()}s by total movement:")
+        print("-" * 40)
+        for entity, row in top_movers.iterrows():
+            print(f"  {entity}: {row['total']:.2f} (X: {row['x_delta']:.2f}, Y: {row['y_delta']:.2f})")
+
+
+def get_quadrant_counts(results_df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Get count of entities in each quadrant.
+
+    Args:
+        results_df: Results from fit_priority_matrix()
+
+    Returns:
+        DataFrame with quadrant counts and percentages
+
+    Examples:
+        >>> counts = get_quadrant_counts(results_df)
+        >>> print(counts)
+    """
+    if results_df.empty:
+        return pd.DataFrame(columns=["quadrant", "count", "percentage"])
+
+    counts = results_df["quadrant"].value_counts().sort_index()
+    total = len(results_df)
+
+    summary = pd.DataFrame({
+        "quadrant": counts.index,
+        "count": counts.values,
+        "percentage": (counts.values / total * 100).round(1)
+    })
+
+    return summary
+
+
+def get_transition_counts(transitions_df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Get count of transitions by risk level.
+
+    Args:
+        transitions_df: DataFrame from extract_transitions()
+
+    Returns:
+        DataFrame with transition counts by risk level
+
+    Examples:
+        >>> counts = get_transition_counts(transitions_df)
+        >>> print(counts)
+    """
+    if transitions_df.empty:
+        return pd.DataFrame(columns=["risk_level", "count", "percentage"])
+
+    counts = transitions_df["risk_level"].value_counts()
+    total = len(transitions_df)
+
+    summary = pd.DataFrame({
+        "risk_level": counts.index,
+        "count": counts.values,
+        "percentage": (counts.values / total * 100).round(1)
+    })
+
+    # sort by risk level
+    risk_order = {"critical": 0, "high": 1, "medium": 2, "low": 3, "stable": 4}
+    summary["order"] = summary["risk_level"].map(risk_order)
+    summary = summary.sort_values("order").drop("order", axis=1)
+
+    return summary

priorityx/viz/matrix.py

@@ -0,0 +1,314 @@
+"""Priority matrix scatter plot visualization."""
+
+from typing import List, Optional, Tuple
+
+import matplotlib.pyplot as plt
+import matplotlib.ticker as ticker
+import pandas as pd
+from matplotlib.lines import Line2D
+
+# try to import adjustText for label positioning
+try:
+    from adjustText import adjust_text
+    ADJUSTTEXT_AVAILABLE = True
+except ImportError:
+    ADJUSTTEXT_AVAILABLE = False
+    print("Warning: adjustText not available. Labels may overlap.")
+
+
+def plot_priority_matrix(
+    results_df: pd.DataFrame,
+    entity_name: str = "Entity",
+    title: Optional[str] = None,
+    figsize: Tuple[int, int] = (16, 12),
+    top_n_labels: int = 5,
+    show_quadrant_labels: bool = False,
+    bubble_col: Optional[str] = None,
+    force_show_labels: Optional[List[str]] = None,
+    force_hide_labels: Optional[List[str]] = None,
+    skip_label_min_count: int = 0,
+    save_plot: bool = False,
+    save_csv: bool = False,
+    output_dir: str = "plot",
+    temporal_granularity: str = "quarterly",
+) -> plt.Figure:
+    """
+    Visualize priority matrix as scatter plot.
+
+    Creates a quadrant-based scatter plot showing entity positions based on
+    GLMM random effects (volume and growth).
+
+    Args:
+        results_df: Results from fit_priority_matrix()
+                   Required columns: entity, Random_Intercept, Random_Slope, quadrant, count
+        entity_name: Name for entity type (e.g., "Service", "Component")
+        title: Optional custom title
+        figsize: Figure size (width, height)
+        top_n_labels: Number of entities to label per quadrant
+        show_quadrant_labels: Show quadrant descriptions as background text
+        bubble_col: Optional column for bubble sizing (e.g., "count")
+        force_show_labels: List of entity names to always label
+        force_hide_labels: List of entity names to never label
+        skip_label_min_count: Skip labeling entities with count < threshold
+        save_plot: Save plot to file
+        save_csv: Save data to CSV
+        output_dir: Output directory for saved files
+        temporal_granularity: Time granularity ('quarterly', 'yearly', 'semiannual')
+
+    Returns:
+        Matplotlib figure
+
+    Examples:
+        >>> # basic plot
+        >>> fig = plot_priority_matrix(results_df, entity_name="Service")
+
+        >>> # with custom bubble sizing and labels
+        >>> fig = plot_priority_matrix(
+        ...     results_df,
+        ...     entity_name="Component",
+        ...     bubble_col="count",
+        ...     top_n_labels=10,
+        ...     save_plot=True
+        ... )
+    """
+    # make a copy to avoid modifying original
+    df = results_df.copy()
+
+    # determine bubble sizing
+    if bubble_col and bubble_col in df.columns:
+        # use log scaling for bubble sizes
+        import numpy as np
+        df["size"] = 100 + 900 * (np.log1p(df[bubble_col]) / np.log1p(df[bubble_col].max()))
+    else:
+        # uniform bubble size
+        df["size"] = 200
+
+    # select entities to label
+    df_labelable = df.copy()
+    if skip_label_min_count > 0 and "count" in df.columns:
+        df_labelable = df[df["count"] >= skip_label_min_count]
+
+    # get top N by volume and growth in each quadrant
+    topics_to_label = {}
+    for q in ["Q1", "Q2", "Q3", "Q4"]:
+        topics_to_label[q] = []
+        q_data = df_labelable[df_labelable["quadrant"] == q]
+
+        if not q_data.empty:
+            # top by volume
+            if "count" in q_data.columns:
+                top_volume = q_data.nlargest(top_n_labels, "count").index.tolist()
+                topics_to_label[q].extend(top_volume)
+
+            # top by growth
+            top_growth = q_data.nlargest(top_n_labels, "Random_Slope").index.tolist()
+            for idx in top_growth:
+                if idx not in topics_to_label[q]:
+                    topics_to_label[q].append(idx)
+
+    # apply manual label controls
+    if force_show_labels:
+        for label_name in force_show_labels:
+            matches = df[df["entity"] == label_name]
+            for idx in matches.index:
+                q = df.loc[idx, "quadrant"]
+                if idx not in topics_to_label[q]:
+                    topics_to_label[q].append(idx)
+
+    if force_hide_labels:
+        for label_name in force_hide_labels:
+            matches = df[df["entity"] == label_name]
+            for idx in matches.index:
+                q = df.loc[idx, "quadrant"]
+                if idx in topics_to_label[q]:
+                    topics_to_label[q].remove(idx)
+
+    # create plot
+    plt.figure(figsize=figsize)
+
+    # define colors for each quadrant
+    colors = {
+        "Q1": "#c2104b",  # red - crisis
+        "Q2": "#FF9636",  # orange - investigate
+        "Q3": "#5cb85c",  # green - monitor
+        "Q4": "#792f88",  # purple - low priority
+    }
+
+    # plot all points
+    for q, color in colors.items():
+        q_data = df[df["quadrant"] == q]
+        if not q_data.empty:
+            plt.scatter(
+                q_data["Random_Intercept"],
+                q_data["Random_Slope"],
+                s=q_data["size"],
+                color=color,
+                alpha=0.7,
+                label=f"Q{q[-1]}",
+                zorder=2,
+            )
+
+    # add axis lines
+    plt.axhline(0, color="grey", linestyle="--", alpha=0.7, linewidth=1)
+    plt.axvline(0, color="grey", linestyle="--", alpha=0.7, linewidth=1)
+
+    # get current axis
+    ax = plt.gca()
+
+    # add quadrant labels as background text
+    if show_quadrant_labels:
+        xlim = ax.get_xlim()
+        ylim = ax.get_ylim()
+
+        # compute quadrant centers
+        quadrant_centers = {
+            "Q1": ((0 + xlim[1]) / 2, (0 + ylim[1]) / 2),  # top right
+            "Q2": ((xlim[0] + 0) / 2, (0 + ylim[1]) / 2),  # top left
+            "Q3": ((xlim[0] + 0) / 2, (ylim[0] + 0) / 2),  # bottom left
+            "Q4": ((0 + xlim[1]) / 2, (ylim[0] + 0) / 2),  # bottom right
+        }
+
+        # quadrant descriptions
+        quadrant_labels = {
+            "Q1": "Q1: Crisis\n(High volume, High growth)",
+            "Q2": "Q2: Investigate\n(Low volume, High growth)",
+            "Q3": "Q3: Monitor\n(Low volume, Low growth)",
+            "Q4": "Q4: Low Priority\n(High volume, Low growth)",
+        }
+
+        # place labels
+        for q, (cx, cy) in quadrant_centers.items():
+            ax.text(
+                cx, cy,
+                quadrant_labels[q],
+                ha="center",
+                va="center",
+                fontsize=14,
+                color="gray",
+                alpha=0.45,
+                zorder=0,
+                fontweight="bold",
+            )
+
+    # add entity labels
+    texts = []
+    for q in ["Q1", "Q2", "Q3", "Q4"]:
+        q_data = df[df["quadrant"] == q]
+        for entity_idx in topics_to_label[q]:
+            if entity_idx in q_data.index:
+                row = q_data.loc[entity_idx]
+                label = row["entity"]
+
+                text = plt.text(
+                    row["Random_Intercept"],
+                    row["Random_Slope"],
+                    label,
+                    fontsize=14,
+                    ha="center",
+                    va="center",
+                )
+                texts.append(text)
+
+    # use adjustText to prevent overlaps if available
+    if ADJUSTTEXT_AVAILABLE and texts:
+        adjust_text(
+            texts,
+            arrowprops=dict(
+                arrowstyle="->", color="gray", lw=1.0, alpha=0.7, shrinkA=5, shrinkB=5
+            ),
+            expand_points=(1.5, 1.5),
+            expand_text=(1.2, 1.2),
+            force_text=(0.5, 0.5),
+            force_points=(0.3, 0.3),
+        )
+
+    # fix y-axis formatter
+    ax.yaxis.set_major_locator(
+        ticker.MaxNLocator(integer=False, steps=[1, 2, 5], nbins=7)
+    )
+    ax.yaxis.set_major_formatter(ticker.FormatStrFormatter("%.1f"))
+
+    # create legend with equal-sized bubbles
+    legend_elements = []
+    for q, color in colors.items():
+        legend_elements.append(
+            Line2D(
+                [0], [0],
+                marker="o",
+                color="w",
+                markerfacecolor=color,
+                markersize=10,
+                label=f"Quadrant {q[-1]}",
+            )
+        )
+
+    # set labels
+    plt.xlabel(f"{entity_name} Volume (Relative)", fontsize=13)
+    plt.ylabel(f"{entity_name} Growth Rate (Relative)", fontsize=13)
+
+    # add title if provided
+    if title:
+        plt.title(title, fontsize=16, fontweight="bold", pad=20)
+
+    # place legend
+    plt.legend(
+        handles=legend_elements, loc="lower right", frameon=False, title="Quadrants"
+    )
+
+    plt.tight_layout()
+
+    # add bubble size note if applicable
+    if bubble_col:
+        xlim = ax.get_xlim()
+        ylim = ax.get_ylim()
+        ax.text(
+            xlim[0] + (xlim[1] - xlim[0]) * 0.02,
+            ylim[0] + (ylim[1] - ylim[0]) * 0.02,
+            f"Bubble size represents {bubble_col}",
+            ha="left",
+            va="bottom",
+            fontsize=10,
+            style="italic",
+            alpha=0.7,
+            zorder=3,
+        )
+
+    # save plot if requested
+    if save_plot:
+        import os
+        from datetime import datetime
+
+        os.makedirs(output_dir, exist_ok=True)
+        timestamp = datetime.now().strftime("%Y%m%d")
+        granularity_suffix = {
+            "quarterly": "Q",
+            "yearly": "Y",
+            "semiannual": "S",
+        }.get(temporal_granularity, "Q")
+        save_path = f"{output_dir}/priority_matrix-{entity_name.lower()}-{granularity_suffix}-{timestamp}.png"
+
+        plt.savefig(save_path, dpi=300, bbox_inches="tight", format="png")
+        print(f"Plot saved: {save_path}")
+
+    # save CSV if requested
+    if save_csv:
+        import os
+        from datetime import datetime
+
+        os.makedirs(f"{output_dir}/../results", exist_ok=True)
+        timestamp = datetime.now().strftime("%Y%m%d")
+        granularity_suffix = {
+            "quarterly": "Q",
+            "yearly": "Y",
+            "semiannual": "S",
+        }.get(temporal_granularity, "Q")
+        csv_path = f"{output_dir}/../results/priority_matrix-{entity_name.lower()}-{granularity_suffix}-{timestamp}.csv"
+
+        # save key columns
+        cols_to_save = ["entity", "quadrant", "Random_Intercept", "Random_Slope", "count"]
+        df[[c for c in cols_to_save if c in df.columns]].to_csv(
+            csv_path, index=False
+        )
+        print(f"CSV saved: {csv_path}")
+
+    return plt.gcf()