priorityx 0.2.1__tar.gz → 0.2.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: priorityx
-Version: 0.2.1
+Version: 0.2.3
 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
@@ -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.1 → priorityx-0.2.3}/README.md

@@ -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.1 → priorityx-0.2.3}/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.1 → priorityx-0.2.3}/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.1 → priorityx-0.2.3}/examples/README.md

@@ -16,18 +16,17 @@ pip install git+https://github.com/okkymabruri/priorityx.git
 
 ## Running Examples
 
-**IT Incidents** (1,621 incidents, 10 services)
+**IT Incidents** (1,621 incidents, 10 services) — pulls CSV from GitHub raw
 ```bash
 python examples/incidents/incident_monitoring.py
 ```
 
-**Compliance Violations** (495 violations, 10 departments)
+**Compliance Violations** (495 violations, 10 departments) — synthetic dataset
 ```bash
 python examples/violations/violations_monitoring.py
 ```
 
-**Software Bugs** (576 bugs, 10 components)
-Pre-generated CSV only. Use as input for your own analysis.
+**Software Bugs** (576 bugs, 10 components) — pulls CSV from GitHub raw
 
 ## Output
 

{priorityx-0.2.1 → priorityx-0.2.3}/examples/bugs/bugs_monitoring.py

@@ -1,19 +1,20 @@
-# software bug tracking example
-
+# %%
+# software bug tracking example (data pulled from GitHub raw)
 import pandas as pd
 
 from priorityx.core.glmm import fit_priority_matrix
 from priorityx.viz.matrix import plot_priority_matrix
 
-# load bug reports
-df = pd.read_csv("examples/bugs/bugs.csv")
+RAW_DATA_URL = "https://raw.githubusercontent.com/okkymabruri/priorityx/main/examples/bugs/bugs.csv"
 
-# parse date column
-df["date"] = pd.to_datetime(df["reported_date"])
+# load bug reports from GitHub raw
+df = pd.read_csv(RAW_DATA_URL, parse_dates=["reported_date"])
+df["date"] = df["reported_date"]
 
 # fit priority matrix
 temporal_granularity = "quarterly"
 entity_name = "Component"
+
 results, stats = fit_priority_matrix(
     df,
     entity_col="component",
@@ -33,9 +34,8 @@ plot_priority_matrix(
     show_quadrant_labels=True,
     save_plot=True,
     save_csv=True,
-    output_dir="examples/bugs/plot",
 )
 print()
-print("Outputs saved to examples/bugs/plot/ and examples/bugs/results/")
+print("Outputs saved to plot/ and results/ (under the current working directory)")
 
 # %%

{priorityx-0.2.1 → priorityx-0.2.3}/examples/incidents/incident_monitoring.py

@@ -1,7 +1,10 @@
-# it incident monitoring example
+# %%
+# it incident monitoring example (data pulled from GitHub raw)
 
 import pandas as pd
 
+RAW_DATA_URL = "https://raw.githubusercontent.com/okkymabruri/priorityx/main/examples/incidents/incidents.csv"
+
 from priorityx.core.glmm import fit_priority_matrix
 from priorityx.tracking.movement import track_cumulative_movement
 from priorityx.tracking.transitions import extract_transitions
@@ -18,9 +21,9 @@ from priorityx.utils.helpers import (
     save_dataframe_to_csv,
 )
 
-# load data
-df = pd.read_csv("examples/incidents/incidents.csv")
-df["date"] = pd.to_datetime(df["date"])
+# load data from GitHub raw
+df = pd.read_csv(RAW_DATA_URL, parse_dates=["date"])
+print("Loaded incidents from GitHub raw URL")
 
 print(f"Loaded {len(df)} incidents for {df['service'].nunique()} services")
 print(f"Date range: {df['date'].min()} to {df['date'].max()}")
@@ -52,7 +55,6 @@ plot_priority_matrix(
     show_quadrant_labels=True,
     save_plot=True,
     save_csv=True,
-    output_dir="examples/incidents/plot",
 )
 
 # track movement
@@ -78,7 +80,6 @@ movement_path = save_dataframe_to_csv(
     artifact="trajectories",
     entity_name=entity_name,
     temporal_granularity=temporal_granularity,
-    output_dir="examples/incidents/results",
 )
 print(f"Movement CSV saved: {movement_path}")
 
@@ -89,8 +90,6 @@ plot_entity_trajectories(
     max_entities=5,
     save_plot=True,
     save_csv=True,
-    output_dir="examples/incidents/plot",
-    results_dir="examples/incidents/results",
 )
 
 # detect transitions
@@ -104,7 +103,6 @@ plot_transition_timeline(
     entity_name=entity_name,
     save_plot=True,
     save_csv=True,
-    output_dir="examples/incidents/plot",
     movement_df=movement,
 )
 
@@ -139,13 +137,13 @@ 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)
 
 print()
-print(
-    "Analysis complete. Check examples/incidents/plot/ and examples/incidents/results/"
-)
+print("Analysis complete. Check plot/ and results/ in the current working directory.")
 
 # %%

{priorityx-0.2.1 → priorityx-0.2.3}/examples/violations/violations_monitoring.py

@@ -1,4 +1,4 @@
-import os
+# %%
 import random
 from datetime import datetime, timedelta
 
@@ -12,6 +12,7 @@ from priorityx.viz.timeline import plot_transition_timeline
 from priorityx.utils.helpers import (
     display_quadrant_summary,
     display_transition_summary,
+    save_dataframe_to_csv,
 )
 
 random.seed(42)
@@ -63,11 +64,6 @@ df = pd.DataFrame(data)
 temporal_granularity = "quarterly"
 entity_name = "Department"
 
-PLOT_DIR = "examples/violations/plot"
-RESULTS_DIR = "examples/violations/results"
-os.makedirs(PLOT_DIR, exist_ok=True)
-os.makedirs(RESULTS_DIR, exist_ok=True)
-
 results, stats = fit_priority_matrix(
     df,
     entity_col="department",
@@ -86,7 +82,6 @@ plot_priority_matrix(
     show_quadrant_labels=True,
     save_plot=True,
     save_csv=True,
-    output_dir=PLOT_DIR,
 )
 
 movement, meta = track_cumulative_movement(
@@ -98,17 +93,12 @@ movement, meta = track_cumulative_movement(
     temporal_granularity=temporal_granularity,
 )
 
-timestamp = datetime.now().strftime("%Y%m%d")
-granularity_suffix = {
-    "quarterly": "Q",
-    "yearly": "Y",
-    "semiannual": "S",
-}.get(temporal_granularity, "Q")
-movement_path = (
-    f"{RESULTS_DIR}/trajectories-{entity_name.lower()}-"
-    f"{granularity_suffix}-{timestamp}.csv"
+movement_path = save_dataframe_to_csv(
+    movement,
+    artifact="trajectories",
+    entity_name=entity_name,
+    temporal_granularity=temporal_granularity,
 )
-movement.to_csv(movement_path, index=False)
 print(f"Movement CSV saved: {movement_path}")
 transitions = extract_transitions(movement, focus_risk_increasing=True)
 
@@ -120,9 +110,10 @@ plot_transition_timeline(
     entity_name=entity_name,
     save_plot=True,
     save_csv=True,
-    output_dir=PLOT_DIR,
     movement_df=movement,
 )
 
 print()
-print("Outputs saved to examples/violations/plot/ and examples/violations/results/")
+print("Outputs saved to plot/ and results/ in the current working directory.")
+
+# %%

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

@@ -1,6 +1,6 @@
 [project]
 name = "priorityx"
-version = "0.2.1"
+version = "0.2.3"
 description = "Entity prioritization and escalation detection using GLMM statistical models"
 authors = [
     {name = "Okky Mabruri", email = "okkymbrur@gmail.com"}
@@ -39,6 +39,8 @@ build-backend = "hatchling.build"
 [dependency-groups]
 dev = [
     "jupyter>=1.1.1",
+    "jupytext>=1.18.1",
+    "mssql-python>=1.0.0",
     "polars>=1.35.1",
     "priorityx",
     "pyarrow>=22.0.0",

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

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

{priorityx-0.2.1 → priorityx-0.2.3}/src/priorityx/core/glmm.py

@@ -3,6 +3,7 @@
 from typing import Dict, Literal, Optional, Tuple
 from datetime import timedelta
 import os
+import warnings
 import numpy as np
 
 import pandas as pd
@@ -71,6 +72,7 @@ def fit_priority_matrix(
     temporal_granularity: Literal["yearly", "quarterly", "semiannual"] = "yearly",
     vcp_p: float = DEFAULT_VCP_P,
     fe_p: float = DEFAULT_FE_P,
+    verbose: bool = False,
 ) -> Tuple[pd.DataFrame, Dict]:
     """
     Fit Poisson GLMM to classify entities into priority quadrants.
@@ -87,6 +89,7 @@ def fit_priority_matrix(
         temporal_granularity: Time aggregation level
         vcp_p: Random effects prior scale
         fe_p: Fixed effects prior scale
+        verbose: When True, print diagnostic logs; otherwise stay quiet
 
     Returns:
         Tuple of (results DataFrame, statistics dict)
@@ -94,6 +97,11 @@ def fit_priority_matrix(
     # create copy to avoid modifying original
     df = df.copy()
 
+    if not verbose:
+        warnings.filterwarnings(
+            "ignore", message="VB fitting did not converge", category=UserWarning
+        )
+
     # ensure timestamp column is datetime
     df[timestamp_col] = pd.to_datetime(df[timestamp_col])
 
@@ -129,7 +137,7 @@ def fit_priority_matrix(
         df = df[df[entity_col].isin(valid_entities)]
         n_after_volume_filter = df[entity_col].nunique()
         n_filtered_volume = n_before_volume_filter - n_after_volume_filter
-        if n_filtered_volume > 0:
+        if verbose and n_filtered_volume > 0:
             print(
                 f"  Filtered {n_filtered_volume} entities (<{min_total_count} total count)"
             )
@@ -308,22 +316,14 @@ def fit_priority_matrix(
         fe_p=fe_p,
     )
 
-    # DIAGNOSTIC LOGGING
-    print(f"\n[GLMM DEBUG] Formula: {formula}")
-    print(f"[GLMM DEBUG] N observations: {len(df_prepared)}")
-    print(f"[GLMM DEBUG] N entities: {df_prepared[entity_col].nunique()}")
-    print(f"[GLMM DEBUG] Year range: {df_prepared['year'].min()}-{df_prepared['year'].max()}")
-    print(f"[GLMM DEBUG] Time variable: mean={df_prepared['time'].mean():.6f}, std={df_prepared['time'].std():.6f}")
-    print(f"[GLMM DEBUG] Entity sample: {df_prepared[entity_col].unique()[:5].tolist()}")
-    print(f"[GLMM DEBUG] vcp_p={vcp_p}, fe_p={fe_p}")
-    
-    # Print first entity's data
-    first_entity = df_prepared[entity_col].iloc[0]
-    entity_data = df_prepared[df_prepared[entity_col] == first_entity]
-    print(f"\n[GLMM DEBUG] First entity '{first_entity}' data:")
-    debug_cols = [c for c in ["year", "quarter", "semester", entity_col, "count", "time"] if c in entity_data.columns]
-    print(entity_data[debug_cols].head(10).to_string())
-
+    if verbose:
+        print(f"\n[GLMM DEBUG] Formula: {formula}")
+        print(f"[GLMM DEBUG] N observations: {len(df_prepared)}")
+        print(f"[GLMM DEBUG] N entities: {df_prepared[entity_col].nunique()}")
+        print(f"[GLMM DEBUG] Year range: {df_prepared['year'].min()}-{df_prepared['year'].max()}")
+        print(f"[GLMM DEBUG] Time variable: mean={df_prepared['time'].mean():.6f}, std={df_prepared['time'].std():.6f}")
+        print(f"[GLMM DEBUG] Entity sample: {df_prepared[entity_col].unique()[:5].tolist()}")
+        print(f"[GLMM DEBUG] vcp_p={vcp_p}, fe_p={fe_p}")
     # use variational bayes (returns posterior mean)
     # avoids boundary convergence issues vs map
     _apply_random_seed()