priorityx 0.2.0__tar.gz → 0.2.2__tar.gz

{priorityx-0.2.0 → priorityx-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: priorityx
-Version: 0.2.0
+Version: 0.2.2
 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
@@ -49,7 +49,7 @@ pip install priorityx
 Set `PRIORITYX_GLMM_SEED` (or call `set_glmm_random_seed()`) before running analyses to obtain repeatable GLMM estimates during debugging or CI checks:
 
 ```bash
-PRIORITYX_GLMM_SEED=1234 python tmp/complaints_analysis.py
+PRIORITYX_GLMM_SEED=1234 python your_script.py
 ```
 
 ```python
@@ -74,6 +74,7 @@ plot_priority_matrix(results, entity_name="Service", save_plot=True)
 - GLMM-based priority matrix (Q1–Q4) with entity-level intercept/slope insights
 - Priority-based transition timeline (Crisis / Investigate / Monitor / Low) with spike markers (`*X`, `*Y`, `*XY`)
 - Cumulative movement tracking and trajectory visualizations
+- Transition driver analysis that surfaces top subcategories causing quadrant shifts with spike summaries
 - Deterministic seeding option for reproducible GLMM runs (set `PRIORITYX_GLMM_SEED`)
 
 ## Use Cases

{priorityx-0.2.0 → priorityx-0.2.2}/README.md

@@ -21,7 +21,7 @@ pip install priorityx
 Set `PRIORITYX_GLMM_SEED` (or call `set_glmm_random_seed()`) before running analyses to obtain repeatable GLMM estimates during debugging or CI checks:
 
 ```bash
-PRIORITYX_GLMM_SEED=1234 python tmp/complaints_analysis.py
+PRIORITYX_GLMM_SEED=1234 python your_script.py
 ```
 
 ```python
@@ -46,6 +46,7 @@ plot_priority_matrix(results, entity_name="Service", save_plot=True)
 - GLMM-based priority matrix (Q1–Q4) with entity-level intercept/slope insights
 - Priority-based transition timeline (Crisis / Investigate / Monitor / Low) with spike markers (`*X`, `*Y`, `*XY`)
 - Cumulative movement tracking and trajectory visualizations
+- Transition driver analysis that surfaces top subcategories causing quadrant shifts with spike summaries
 - Deterministic seeding option for reproducible GLMM runs (set `PRIORITYX_GLMM_SEED`)
 
 ## Use Cases

{priorityx-0.2.0 → priorityx-0.2.2}/docs/api-reference.md

@@ -100,8 +100,9 @@ analysis = extract_transition_drivers(
     quarter_to="2024-Q3",
     entity_col="service",
     timestamp_col="date",
-    subcategory_cols=["type", "category"],  # Optional
-    text_col="description"  # Optional
+    subcategory_cols=["type", "category"],  # Optional override; auto-detected if omitted
+    top_n_subcategories=5,
+    min_subcategory_delta=2,
 )
 ```
 
@@ -115,11 +116,18 @@ Analyzes root causes of a quadrant transition.
 - `quarter_to`: Ending quarter (e.g., "2024-Q3")
 - `entity_col`: Entity column name
 - `timestamp_col`: Timestamp column name
-- `subcategory_cols`: Optional list of subcategory columns
-- `text_col`: Optional text column for keyword analysis
+- `subcategory_cols`: Optional list of subcategory columns (auto-detected when omitted)
+- `top_n_subcategories`: Limit of subcategory drivers (default: 3)
+- `min_subcategory_delta`: Minimum delta required for subcategory inclusion (default: 1)
 
 **Returns:**
-- Dictionary with transition overview, magnitude metrics, subcategory drivers, keyword drivers, and priority classification
+- Dictionary with:
+  - `transition`: includes risk-level change and `is_concerning` flag
+  - `magnitude`: cumulative deltas plus period-specific weekly averages and complaint counts
+  - `spike_drivers`: summary notes aligned with spike indicators (`*X`, `*Y`, `*XY`)
+  - `subcategory_drivers`: per-column driver lists obeying the provided knobs
+  - `priority`: priority tier, trigger reason, spike axis
+  - `meta`: diagnostic flags (e.g., whether subcategory columns were auto-detected)
 
 ### classify_priority
 
@@ -222,11 +230,10 @@ Prints formatted summaries of analysis results.
 ```python
 from priorityx.tracking.drivers import display_transition_drivers
 
-display_transition_drivers(analysis, show_keywords=True)
+display_transition_drivers(analysis)
 ```
 
 Prints transition driver analysis in human-readable format.
 
 **Parameters:**
 - `analysis`: Output from extract_transition_drivers()
-- `show_keywords`: Whether to show keyword analysis (default: False)

{priorityx-0.2.0 → priorityx-0.2.2}/docs/quickstart.md

@@ -62,9 +62,14 @@ if not transitions.empty:
         quarter_from=first_transition["from_quarter"],
         quarter_to=first_transition["transition_quarter"],
         entity_col="service",
-        timestamp_col="date"
+        timestamp_col="date",
+        top_n_subcategories=5,
+        min_subcategory_delta=2
     )
     display_transition_drivers(analysis)
+
+    # subcategory columns (e.g., severity/product/topic) are auto-detected
+    # when not provided; pass subcategory_cols=[...] to override.
 ```
 
 ## Data Requirements

{priorityx-0.2.0 → priorityx-0.2.2}/examples/incidents/incident_monitoring.py

@@ -1,6 +1,13 @@
 # it incident monitoring example
 
+from pathlib import Path
+from io import StringIO
+
 import pandas as pd
+import requests
+
+RAW_DATA_URL = "https://raw.githubusercontent.com/okkymabruri/priorityx/main/examples/incidents/incidents.csv"
+LOCAL_DATA_PATH = Path(__file__).parent / "incidents.csv"
 
 from priorityx.core.glmm import fit_priority_matrix
 from priorityx.tracking.movement import track_cumulative_movement
@@ -18,8 +25,15 @@ from priorityx.utils.helpers import (
     save_dataframe_to_csv,
 )
 
-# load data
-df = pd.read_csv("examples/incidents/incidents.csv")
+# load data (prefer hosted CSV so the example works out-of-the-box)
+try:
+    response = requests.get(RAW_DATA_URL, timeout=10)
+    response.raise_for_status()
+    df = pd.read_csv(StringIO(response.text))
+    print("Loaded incidents from GitHub raw URL")
+except Exception:
+    print("Falling back to local incidents.csv")
+    df = pd.read_csv(LOCAL_DATA_PATH)
 df["date"] = pd.to_datetime(df["date"])
 
 print(f"Loaded {len(df)} incidents for {df['service'].nunique()} services")
@@ -139,6 +153,8 @@ if len(critical_transitions) > 0:
             quarter_to=trans["transition_quarter"],
             entity_col="service",
             timestamp_col="date",
+            top_n_subcategories=5,
+            min_subcategory_delta=2,
         )
 
         display_transition_drivers(driver_analysis)

{priorityx-0.2.0 → priorityx-0.2.2}/pyproject.toml

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

{priorityx-0.2.0 → priorityx-0.2.2}/src/priorityx/__init__.py

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