priorityx 0.2.3__tar.gz → 0.2.5__tar.gz

{priorityx-0.2.3 → priorityx-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: priorityx
-Version: 0.2.3
+Version: 0.2.5
 Summary: Entity prioritization and escalation detection using GLMM statistical models
 Project-URL: Homepage, https://github.com/okkymabruri/priorityx
 Project-URL: Repository, https://github.com/okkymabruri/priorityx

{priorityx-0.2.3 → priorityx-0.2.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "priorityx"
-version = "0.2.3"
+version = "0.2.5"
 description = "Entity prioritization and escalation detection using GLMM statistical models"
 authors = [
     {name = "Okky Mabruri", email = "okkymbrur@gmail.com"}

{priorityx-0.2.3 → priorityx-0.2.5}/src/priorityx/__init__.py

@@ -1,6 +1,6 @@
 """priorityx: Entity prioritization and escalation detection using GLMM statistical models."""
 
-__version__ = "0.2.3"
+__version__ = "0.2.5"
 
 # API will be imported
 

{priorityx-0.2.3 → priorityx-0.2.5}/src/priorityx/tracking/drivers.py

@@ -82,7 +82,9 @@ def _detect_subcategory_columns(
                 continue
 
             series = df[col]
-            if pd.api.types.is_object_dtype(series) or pd.api.types.is_categorical_dtype(series):
+            if pd.api.types.is_object_dtype(
+                series
+            ) or pd.api.types.is_categorical_dtype(series):
                 unique_vals = series.nunique(dropna=True)
                 if 1 < unique_vals <= max_unique:
                     detected.append(col)
@@ -262,8 +264,8 @@ def extract_transition_drivers(
     entity_col: str = "entity",
     timestamp_col: str = "date",
     subcategory_cols: Optional[List[str]] = None,
-    top_n_subcategories: int = 3,
-    min_subcategory_delta: int = 1,
+    top_n_subcategories: int = 5,
+    min_subcategory_delta: int = 2,
 ) -> Dict:
     """
     Extract key drivers of a quadrant transition.
@@ -364,10 +366,8 @@ def extract_transition_drivers(
     }
 
     # magnitude metrics
-    if "complaints_to_date" in from_row.index:
-        count_col_name = "complaints_to_date"
-    elif "count_to_date" in from_row.index:
-        count_col_name = "count_to_date"
+    if "cumulative_count" in from_row.index:
+        count_col_name = "cumulative_count"
     else:
         count_col_name = None
 
@@ -454,7 +454,7 @@ def extract_transition_drivers(
             from_period_data,
             to_period_data,
             effective_subcats,
-            period_increase,
+            absolute_delta,
             top_n=top_n_subcategories,
             min_delta=min_subcategory_delta,
         )
@@ -467,6 +467,7 @@ def extract_transition_drivers(
 
     return result
 
+
 def _summarize_spike_drivers(priority_info: Dict, magnitude: Dict) -> Dict:
     """Create a compact summary describing what triggered spike flags."""
 
@@ -514,7 +515,7 @@ def _analyze_subcategory_drivers(
     from_data: pd.DataFrame,
     to_data: pd.DataFrame,
     subcategory_cols: List[str],
-    period_increase: int,
+    absolute_delta: int,
     top_n: int = 3,
     min_delta: int = 1,
 ) -> Dict:
@@ -556,9 +557,10 @@ def _analyze_subcategory_drivers(
         ).fillna(0)
 
         comparison["delta"] = comparison["count_to"] - comparison["count_from"]
-        comparison["percent_of_change"] = (
-            (comparison["delta"] / period_increase * 100) if period_increase > 0 else 0
-        )
+        if absolute_delta > 0:
+            comparison["percent_of_change"] = comparison["delta"] / absolute_delta * 100
+        else:
+            comparison["percent_of_change"] = 0.0
 
         # classify driver type
         def classify_driver_type(row):
@@ -588,12 +590,13 @@ def _analyze_subcategory_drivers(
                 }
             )
 
-        # calculate explanation power
-        top_explain_pct = (
-            sum([d["delta"] for d in drivers_list]) / period_increase * 100
-            if period_increase > 0
-            else 0
-        )
+        # calculate explanation power (share of cumulative volume delta)
+        if absolute_delta > 0:
+            top_explain_pct = (
+                sum(d["delta"] for d in drivers_list) / absolute_delta * 100
+            )
+        else:
+            top_explain_pct = 0.0
 
         drivers_by_subcategory[subcat_col] = {
             "top_drivers": drivers_list,
@@ -604,92 +607,69 @@ def _analyze_subcategory_drivers(
 
 
 def display_transition_drivers(analysis: Dict) -> None:
-    """
-    Print transition driver analysis in human-readable format.
+    """Print a concise, diagnoser-style summary of transition drivers."""
 
-    Args:
-        analysis: Output from extract_transition_drivers()
-
-    Examples:
-        >>> display_transition_drivers(analysis)
-    """
     trans = analysis["transition"]
     mag = analysis["magnitude"]
     vol = mag["volume_change"]
     growth = mag["growth_change"]
     priority = analysis["priority"]
+    spike = analysis.get("spike_drivers", {})
+    subcats = analysis.get("subcategory_drivers", {})
 
     print()
     print("TRANSITION DRIVER ANALYSIS")
 
-    # transition overview
-    print()
-    print(f"Entity: {trans['entity']}")
-    print(f"Period: {trans['from_quarter']} -> {trans['to_quarter']}")
-    print(f"Quadrant: {trans.get('from_quadrant_label', trans['from_quadrant'])} -> {trans.get('to_quadrant_label', trans['to_quadrant'])}")
-    if trans.get("risk_level_change"):
-        print(f"Risk level: {trans['risk_level_change']}")
-
-    if trans["quadrant_changed"]:
-        print("Status: Quadrant transition detected")
-    else:
-        print("Status: Within-quadrant movement")
-
-    # priority
-    print()
-    print(f"Priority: P{priority['priority']} ({priority['priority_name']})")
-    print(f"Reason: {priority['trigger_reason']}")
-    if priority.get("spike_axis"):
-        print(f"Spike axis: {priority['spike_axis']}")
-    if analysis.get("spike_drivers"):
-        spike = analysis["spike_drivers"]
-        print("Spike summary:")
-        for note in spike.get("notes", []):
-            print(f"  - {note}")
-
-    # magnitude
-    print()
-    print("Magnitude:")
+    # headline
     print(
-        f"  Volume: {vol['count_from']:,} -> {vol['count_to']:,} "
-        f"(delta {vol['absolute_delta']:+,}, {vol['percent_change']:+.1f}%)"
+        f"[P{priority['priority']}] {trans['entity']}: "
+        f"{trans['from_quarter']} -> {trans['to_quarter']} "
+        f"({trans.get('from_quadrant', '')} -> {trans.get('to_quadrant', '')})"
     )
+    if trans.get("risk_level_change"):
+        print(f"  Risk: {trans['risk_level_change']}")
+
+    # core metrics
     print(
-        f"  X-axis: {vol['x_from']:.2f} -> {vol['x_to']:.2f} (delta {vol['x_delta']:+.2f})"
+        "  Cumulative volume (all time): "
+        f"{vol['count_from']:,} -> {vol['count_to']:,} "
+        f"(Δ {vol['absolute_delta']:+,}, {vol['percent_change']:+.1f}%)"
     )
     print(
-        f"  Y-axis: {growth['y_from']:.2f} -> {growth['y_to']:.2f} (delta {growth['y_delta']:+.2f})"
+        "  X/Y:    "
+        f"X {vol['x_from']:.2f} -> {vol['x_to']:.2f} (Δ {vol['x_delta']:+.2f}), "
+        f"Y {growth['y_from']:.2f} -> {growth['y_to']:.2f} (Δ {growth['y_delta']:+.2f})"
     )
-    if "weekly_avg_from" in growth:
+    if "period_counts" in mag:
+        pc = mag["period_counts"]
         print(
-            f"  Weekly avg: {growth['weekly_avg_from']:.1f} -> {growth['weekly_avg_to']:.1f}"
+            "  Period volume (quarter): "
+            f"{pc['count_from']} -> {pc['count_to']} "
+            f"(Δ {pc['absolute_delta']:+})"
         )
 
-    if "period_counts" in mag:
-        period_counts = mag["period_counts"]
-        print(
-            "  Period complaints: "
-            f"{period_counts['count_from']} -> {period_counts['count_to']} "
-            f"(delta {period_counts['absolute_delta']:+})"
+    # priority + spike summary
+    print(f"  Priority: P{priority['priority']} ({priority['priority_name']})")
+    print(f"  Trigger:  {priority['trigger_reason']}")
+
+    for note in spike.get("notes", []):
+        print(f"  · {note}")
+
+    # subcategory drivers (if available)
+    for subcat_col, drivers_data in subcats.items():
+        top_drivers = drivers_data.get("top_drivers", [])
+        explain_pct = drivers_data.get(
+            "top_n_explain_pct", drivers_data.get("top_3_explain_pct", 0.0)
         )
+        if not top_drivers:
+            continue
 
-    # subcategory drivers
-    if "subcategory_drivers" in analysis:
-        for subcat_col, drivers_data in analysis["subcategory_drivers"].items():
-            top_drivers = drivers_data["top_drivers"]
-            explain_pct = drivers_data.get("top_n_explain_pct", drivers_data.get("top_3_explain_pct", 0.0))
-
-            if top_drivers:
-                print()
-                print(
-                    f"Top drivers by {subcat_col} (explain {explain_pct:.1f}% of change):"
-                )
-                for i, driver in enumerate(top_drivers, 1):
-                    print(f"  {i}. {driver['name']}")
-                    print(
-                        f"     {driver['count_from']:,} -> {driver['count_to']:,} "
-                        f"(delta {driver['delta']:+,}, {driver['percent_of_change']:.1f}%)"
-                    )
-                    print(f"     Type: {driver['driver_type']}")
+        print(f"  Drivers by {subcat_col} (explain {explain_pct:.1f}% of change):")
+        for d in top_drivers:
+            print(
+                f"    - {d['name']}: "
+                f"{d['count_from']:,} -> {d['count_to']:,} "
+                f"(Δ {d['delta']:+,}, {d['percent_of_change']:.1f}%, {d['driver_type']})"
+            )
 
-    print()
+    print()  # trailing newline for readability

{priorityx-0.2.3 → priorityx-0.2.5}/src/priorityx/tracking/movement.py

@@ -5,6 +5,8 @@ from typing import Optional, Sequence, Union
 
 import pandas as pd
 
+from priorityx.utils.helpers import latest_artifact_csv, save_dataframe_to_csv
+
 
 def _is_quarter_start(ts: pd.Timestamp) -> bool:
     """Check if timestamp is the first day of a calendar quarter."""
@@ -216,8 +218,9 @@ def track_cumulative_movement(
     Returns:
         Tuple of (movement_df, metadata_dict)
         - movement_df: Quarter-by-quarter tracking with columns:
-          [entity, quarter, count_to_date, period_x, period_y, period_quadrant,
-           global_quadrant, global_x, global_y, count_total, x_delta, y_delta, volume_delta]
+          [entity, quarter, period_count, cumulative_count, period_x, period_y,
+           period_quadrant, global_quadrant, global_x, global_y,
+           count_total, x_delta, y_delta, quadrant_differs]
         - metadata_dict: Tracking statistics and configuration
 
     Examples:
@@ -245,7 +248,8 @@ def track_cumulative_movement(
             columns=[
                 "entity",
                 "quarter",
-                "count_to_date",
+                "period_count",
+                "cumulative_count",
                 "period_x",
                 "period_y",
                 "period_quadrant",
@@ -253,8 +257,12 @@ def track_cumulative_movement(
                 "global_x",
                 "global_y",
                 "count_total",
+                "x_delta",
+                "y_delta",
+                "quadrant_differs",
             ]
         )
+
         metadata = {
             "entities_tracked": 0,
             "quarters_analyzed": 0,
@@ -395,7 +403,7 @@ def track_cumulative_movement(
                         {
                             "entity": entity,
                             "quarter": quarter_name,
-                            "count_to_date": row["count"],
+                            "cumulative_count": row["count"],
                             "period_x": row["Random_Intercept"],
                             "period_y": row["Random_Slope"],
                             "period_quadrant": row["quadrant"],
@@ -419,7 +427,8 @@ def track_cumulative_movement(
             columns=[
                 "entity",
                 "quarter",
-                "count_to_date",
+                "period_count",
+                "cumulative_count",
                 "period_x",
                 "period_y",
                 "period_quadrant",
@@ -429,7 +438,7 @@ def track_cumulative_movement(
                 "count_total",
                 "x_delta",
                 "y_delta",
-                "volume_delta",
+                "quadrant_differs",
             ]
         )
 
@@ -442,13 +451,40 @@ def track_cumulative_movement(
     # calculate deltas
     movement_df["x_delta"] = movement_df.groupby("entity")["period_x"].diff()
     movement_df["y_delta"] = movement_df.groupby("entity")["period_y"].diff()
-    movement_df["volume_delta"] = movement_df.groupby("entity")["count_to_date"].diff()
+
+    # new event count per period
+    movement_df["period_count"] = movement_df.groupby("entity")[
+        "cumulative_count"
+    ].diff()
 
     # detect quadrant divergence
     movement_df["quadrant_differs"] = (
         movement_df["period_quadrant"] != movement_df["global_quadrant"]
     )
 
+    # reorder columns for readability
+    cols = [
+        "entity",
+        "quarter",
+        "period_count",
+        "cumulative_count",
+        "period_x",
+        "period_y",
+        "period_quadrant",
+        "global_quadrant",
+        "global_x",
+        "global_y",
+        "count_total",
+        "x_delta",
+        "y_delta",
+        "quadrant_differs",
+    ]
+    # keep any extra columns at the end
+    movement_df = movement_df[
+        [c for c in cols if c in movement_df.columns]
+        + [c for c in movement_df.columns if c not in cols]
+    ]
+
     print(f"Tracked {len(movement_df)} entity-quarter observations")
     print(f"Entities tracked: {movement_df['entity'].nunique()}")
     print(f"Periods covered: {movement_df['quarter'].nunique()}")
@@ -472,3 +508,49 @@ def track_cumulative_movement(
     }
 
     return movement_df, metadata
+
+
+def load_or_track_movement(
+    df_raw: pd.DataFrame,
+    *,
+    entity_name: str,
+    entity_col: str,
+    timestamp_col: str,
+    quarters,
+    min_total_count: int,
+    temporal_granularity: str = "quarterly",
+    output_dir: str = "results/csv",
+    use_cache: bool = True,
+) -> tuple[pd.DataFrame, str | None]:
+    """Load latest movement CSV for entity or compute and save.
+
+    When ``use_cache`` is True, tries to load the most recent
+    ``movement-<entity_slug>-*.csv`` from ``output_dir``. If not
+    found, runs tracking and saves a fresh movement CSV.
+    """
+
+    csv_path: str | None = None
+    if use_cache:
+        csv_path = latest_artifact_csv("movement", entity_name, output_dir)
+        if csv_path:
+            movement_df = pd.read_csv(csv_path)
+            return movement_df, csv_path
+
+    movement_df, _meta = track_cumulative_movement(
+        df_raw,
+        entity_col=entity_col,
+        timestamp_col=timestamp_col,
+        quarters=quarters,
+        min_total_count=min_total_count,
+        temporal_granularity=temporal_granularity,
+    )
+
+    csv_path = save_dataframe_to_csv(
+        movement_df,
+        artifact="movement",
+        entity_name=entity_name,
+        temporal_granularity=temporal_granularity,
+        output_dir=output_dir,
+    )
+
+    return movement_df, csv_path

{priorityx-0.2.3 → priorityx-0.2.5}/src/priorityx/utils/helpers.py

@@ -2,6 +2,7 @@
 
 import os
 from datetime import datetime
+from pathlib import Path
 
 import pandas as pd
 
@@ -298,3 +299,21 @@ def save_dataframe_to_csv(
     )
     df.to_csv(output_path, index=False)
     return output_path
+
+
+def latest_artifact_csv(
+    artifact: str,
+    entity_name: str,
+    output_dir: str = "results/csv",
+) -> str | None:
+    """Find the latest CSV for a given artifact/entity pair.
+
+    Assumes filenames follow ``generate_output_path`` convention:
+    ``<output_dir>/<artifact>-<entity_slug>-<granularity>-<YYYYMMDD>.csv``.
+    """
+
+    slug = entity_name.lower().replace(" ", "_")
+    directory = Path(output_dir)
+    pattern = f"{artifact}-{slug}-*.csv"
+    matches = sorted(directory.glob(pattern))
+    return str(matches[-1]) if matches else None

{priorityx-0.2.3 → priorityx-0.2.5}/src/priorityx/viz/timeline.py

@@ -222,32 +222,35 @@ def plot_transition_timeline(
                 if len(prev_quarter_data) > 0:
                     prev_row = prev_quarter_data.iloc[-1]
 
-                    # get count column (handle both naming conventions)
-                    count_col = (
-                        "complaints_to_date"
-                        if "complaints_to_date" in row.index
-                        else "count_to_date"
-                    )
-
-                    complaints_delta = int(row[count_col] - prev_row[count_col])
-                    percent_change = (
-                        (row[count_col] - prev_row[count_col])
-                        / prev_row[count_col]
-                        * 100
-                        if prev_row[count_col] > 0
-                        else 0
-                    )
-
-                    priority, _, spike_axis = classify_priority(
-                        from_quadrant=transition["from_quadrant"],
-                        to_quadrant=transition["to_quadrant"],
-                        x=row["period_x"],
-                        y=row["period_y"],
-                        x_delta=row["period_x"] - prev_row["period_x"],
-                        y_delta=row["period_y"] - prev_row["period_y"],
-                        complaints_delta=complaints_delta,
-                        percent_change=percent_change,
-                    )
+                    # use cumulative_count for movement magnitude when available
+                    if (
+                        "cumulative_count" in row.index
+                        and "cumulative_count" in prev_row.index
+                    ):
+                        count_col = "cumulative_count"
+
+                        complaints_delta = int(row[count_col] - prev_row[count_col])
+                        percent_change = (
+                            (row[count_col] - prev_row[count_col])
+                            / prev_row[count_col]
+                            * 100
+                            if prev_row[count_col] > 0
+                            else 0
+                        )
+
+                        priority, _, spike_axis = classify_priority(
+                            from_quadrant=transition["from_quadrant"],
+                            to_quadrant=transition["to_quadrant"],
+                            x=row["period_x"],
+                            y=row["period_y"],
+                            x_delta=row["period_x"] - prev_row["period_x"],
+                            y_delta=row["period_y"] - prev_row["period_y"],
+                            complaints_delta=complaints_delta,
+                            percent_change=percent_change,
+                        )
+                    else:
+                        priority = 2
+                        spike_axis = None
                 else:
                     priority = 2  # default to "investigate"
             else:

{priorityx-0.2.3 → priorityx-0.2.5}/src/priorityx/viz/trajectory.py

@@ -15,6 +15,7 @@ warnings.filterwarnings(
     category=UserWarning,
 )
 
+
 def plot_entity_trajectories(
     movement_df: pd.DataFrame,
     entity_name: str = "Entity",
@@ -69,6 +70,25 @@ def plot_entity_trajectories(
         print("No movement data to visualize")
         return None
 
+    # trim trajectories after last quarter with new events
+    if "period_count" in movement_df.columns:
+        df_trim = movement_df.copy()
+        active = df_trim[df_trim["period_count"].fillna(0) > 0]
+        if not active.empty:
+            last_active = active.groupby("entity")["quarter"].max()
+            df_trim = df_trim.merge(
+                last_active.rename("last_active_quarter"),
+                on="entity",
+                how="left",
+            )
+            # keep only entities that ever had positive period_count
+            # and cut them at their last active quarter
+            df_trim = df_trim[
+                df_trim["last_active_quarter"].notna()
+                & (df_trim["quarter"] <= df_trim["last_active_quarter"])
+            ]
+            movement_df = df_trim
+
     # select entities to plot
     if highlight_entities:
         entities_to_plot = [
@@ -129,11 +149,11 @@ def plot_entity_trajectories(
 
         # get color from global quadrant
         global_quad = entity_data.iloc[0]["global_quadrant"]
-        
+
         # find alternative color if already used
         base_color = colors.get(global_quad, "#95a5a6")
         color = base_color
-        
+
         used_colors[base_color] = used_colors.get(base_color, 0) + 1
         if used_colors[base_color] > 1:
             # generate darker shade for same quadrant (better contrast)
@@ -243,7 +263,13 @@ def plot_entity_trajectories(
     from matplotlib.lines import Line2D
 
     quadrant_legend = [
-        Line2D([0], [0], color=colors[quadrant], linewidth=3, label=quadrant_display[quadrant])
+        Line2D(
+            [0],
+            [0],
+            color=colors[quadrant],
+            linewidth=3,
+            label=quadrant_display[quadrant],
+        )
         for quadrant in ["Q1", "Q2", "Q3", "Q4"]
     ]
     legend_fontsize = 15
@@ -257,11 +283,11 @@ def plot_entity_trajectories(
     )
 
     # remove plot borders for cleaner look
-    ax.spines['top'].set_visible(False)
-    ax.spines['right'].set_visible(False)
-    ax.spines['bottom'].set_visible(False)
-    ax.spines['left'].set_visible(False)
-    
+    ax.spines["top"].set_visible(False)
+    ax.spines["right"].set_visible(False)
+    ax.spines["bottom"].set_visible(False)
+    ax.spines["left"].set_visible(False)
+
     # keep quadrant dividers but make them more subtle
     ax.axhline(0, color="grey", linestyle="--", alpha=0.7, linewidth=1, zorder=0)
     ax.axvline(0, color="grey", linestyle="--", alpha=0.7, linewidth=1, zorder=0)

{priorityx-0.2.3 → priorityx-0.2.5}/tests/test_drivers.py

@@ -63,7 +63,7 @@ def test_extract_transition_drivers_basic():
             "period_quadrant": ["Q3", "Q2"],
             "period_x": [-0.2, -0.1],
             "period_y": [-0.1, 0.2],
-            "count_to_date": [50, 80],
+            "cumulative_count": [50, 80],
         }
     )
 
@@ -136,7 +136,7 @@ def test_extract_transition_drivers_manual_subcategory_controls():
             "period_quadrant": ["Q3", "Q2"],
             "period_x": [-0.3, -0.05],
             "period_y": [-0.2, 0.3],
-            "complaints_to_date": [40, 90],
+            "cumulative_count": [40, 90],
         }
     )
 
@@ -205,7 +205,7 @@ def test_extract_transition_drivers_fallback_detection():
             "period_quadrant": ["Q4", "Q2"],
             "period_x": [-0.4, 0.1],
             "period_y": [-0.2, 0.3],
-            "complaints_to_date": [30, 65],
+            "cumulative_count": [30, 65],
         }
     )
 

{priorityx-0.2.3 → priorityx-0.2.5}/uv.lock

@@ -2270,7 +2270,7 @@ wheels = [
 
 [[package]]
 name = "priorityx"
-version = "0.2.2"
+version = "0.2.3"
 source = { editable = "." }
 dependencies = [
     { name = "adjusttext" },