priorityx 0.2.6__tar.gz → 0.3.0__tar.gz

{priorityx-0.2.6 → priorityx-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: priorityx
-Version: 0.2.6
+Version: 0.3.0
 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
@@ -44,29 +44,20 @@ pip install priorityx
 
 ## Quick Start
 
-### Deterministic runs
-
-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 your_script.py
-```
-
 ```python
 import pandas as pd
-from priorityx.core.glmm import fit_priority_matrix
-from priorityx.viz.matrix import plot_priority_matrix
+import priorityx as px
 
 df = pd.read_csv("data.csv")
 
-results, stats = fit_priority_matrix(
+results, stats = px.fit_priority_matrix(
     df,
     entity_col="service",
     timestamp_col="date",
-    temporal_granularity="quarterly"
+    temporal_granularity="quarterly",
 )
 
-plot_priority_matrix(results, entity_name="Service", save_plot=True)
+px.plot_priority_matrix(results, entity_name="Service", save_plot=True)
 ```
 
 ## Features

{priorityx-0.2.6 → priorityx-0.3.0}/README.md

@@ -16,29 +16,20 @@ pip install priorityx
 
 ## Quick Start
 
-### Deterministic runs
-
-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 your_script.py
-```
-
 ```python
 import pandas as pd
-from priorityx.core.glmm import fit_priority_matrix
-from priorityx.viz.matrix import plot_priority_matrix
+import priorityx as px
 
 df = pd.read_csv("data.csv")
 
-results, stats = fit_priority_matrix(
+results, stats = px.fit_priority_matrix(
     df,
     entity_col="service",
     timestamp_col="date",
-    temporal_granularity="quarterly"
+    temporal_granularity="quarterly",
 )
 
-plot_priority_matrix(results, entity_name="Service", save_plot=True)
+px.plot_priority_matrix(results, entity_name="Service", save_plot=True)
 ```
 
 ## Features

{priorityx-0.2.6 → priorityx-0.3.0}/docs/api-reference.md

@@ -5,9 +5,9 @@
 ### fit_priority_matrix
 
 ```python
-from priorityx.core.glmm import fit_priority_matrix
+import priorityx as px
 
-results, stats = fit_priority_matrix(
+results, stats = px.fit_priority_matrix(
     df,
     entity_col,
     timestamp_col,
@@ -50,9 +50,9 @@ Fits Poisson GLMM to classify entities into priority quadrants.
 ### track_cumulative_movement
 
 ```python
-from priorityx.tracking.movement import track_cumulative_movement
+import priorityx as px
 
-movement, meta = track_cumulative_movement(
+movement, meta = px.track_cumulative_movement(
     df,
     entity_col,
     timestamp_col,
@@ -74,9 +74,9 @@ Tracks entity movement through priority quadrants over time.
 ### extract_transitions
 
 ```python
-from priorityx.tracking.transitions import extract_transitions
+import priorityx as px
 
-transitions = extract_transitions(
+transitions = px.extract_transitions(
     movement_df,
     focus_risk_increasing=True
 )
@@ -90,9 +90,9 @@ Extracts quadrant transitions from movement data.
 ### extract_transition_drivers
 
 ```python
-from priorityx.tracking.drivers import extract_transition_drivers
+import priorityx as px
 
-analysis = extract_transition_drivers(
+analysis = px.extract_transition_drivers(
     movement_df,
     df_raw,
     entity_name="Service A",
@@ -156,9 +156,9 @@ Classifies supervisory priority (1=Critical, 2=Investigate, 3=Monitor, 4=Low).
 ### plot_priority_matrix
 
 ```python
-from priorityx.viz.matrix import plot_priority_matrix
+import priorityx as px
 
-fig = plot_priority_matrix(
+fig = px.plot_priority_matrix(
     results_df,
     entity_name="Entity",
     figsize=(16, 12),
@@ -174,9 +174,9 @@ Creates scatter plot of priority matrix.
 ### plot_transition_timeline
 
 ```python
-from priorityx.viz.timeline import plot_transition_timeline
+import priorityx as px
 
-fig = plot_transition_timeline(
+fig = px.plot_transition_timeline(
     transitions_df,
     entity_name="Entity",
     filter_risk_levels=["critical", "high"],
@@ -192,9 +192,9 @@ Creates timeline heatmap of transitions. Passing `movement_df` is required to co
 ### plot_entity_trajectories
 
 ```python
-from priorityx.viz.trajectory import plot_entity_trajectories
+import priorityx as px
 
-fig = plot_entity_trajectories(
+fig = px.plot_entity_trajectories(
     movement_df,
     entity_name="Entity",
     max_entities=10,

{priorityx-0.2.6 → priorityx-0.3.0}/docs/quickstart.md

@@ -10,36 +10,32 @@ pip install priorityx
 
 ```python
 import pandas as pd
-from priorityx.core.glmm import fit_priority_matrix
-from priorityx.viz.matrix import plot_priority_matrix
+import priorityx as px
 
 # load your data
 df = pd.read_csv("your_data.csv")
 df["date"] = pd.to_datetime(df["date"])
 
 # fit priority matrix
-results, stats = fit_priority_matrix(
+results, stats = px.fit_priority_matrix(
     df,
     entity_col="service",      # your entity column
     timestamp_col="date",      # your date column
     temporal_granularity="quarterly",
-    min_observations=8
+    min_observations=8,
 )
 
 # visualize
-plot_priority_matrix(results, entity_name="Service", save_plot=True)
+px.plot_priority_matrix(results, entity_name="Service", save_plot=True)
 ```
 
 ## Full Workflow
 
 ```python
-from priorityx.tracking.movement import track_cumulative_movement
-from priorityx.tracking.transitions import extract_transitions
-from priorityx.tracking.drivers import extract_transition_drivers, display_transition_drivers
-from priorityx.viz.timeline import plot_transition_timeline
+import priorityx as px
 
 # track movement over time
-movement, meta = track_cumulative_movement(
+movement, meta = px.track_cumulative_movement(
     df,
     entity_col="service",
     timestamp_col="date",
@@ -47,15 +43,15 @@ movement, meta = track_cumulative_movement(
 )
 
 # detect transitions
-transitions = extract_transitions(movement)
+transitions = px.extract_transitions(movement)
 
 # visualize transitions
-plot_transition_timeline(transitions, entity_name="Service", save_plot=True)
+px.plot_transition_timeline(transitions, entity_name="Service", save_plot=True)
 
 # analyze drivers for specific transition
 if not transitions.empty:
     first_transition = transitions.iloc[0]
-    analysis = extract_transition_drivers(
+    analysis = px.extract_transition_drivers(
         movement_df=movement,
         df_raw=df,
         entity_name=first_transition["entity"],
@@ -66,7 +62,7 @@ if not transitions.empty:
         top_n_subcategories=5,
         min_subcategory_delta=2
     )
-    display_transition_drivers(analysis)
+    px.display_transition_drivers(analysis)
 
     # subcategory columns (e.g., severity/product/topic) are auto-detected
     # when not provided; pass subcategory_cols=[...] to override.
@@ -86,3 +82,11 @@ By default, outputs saved to:
 - **`results/`** - All CSV data files (entity scores, transitions, movement tracking)
 
 You can customize output directories using the `output_dir` parameter in visualization functions.
+
+## Deterministic runs
+
+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 your_script.py
+```

{priorityx-0.2.6 → priorityx-0.3.0}/examples/bugs/bugs_monitoring.py

@@ -2,8 +2,7 @@
 # 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
+import priorityx as px
 
 RAW_DATA_URL = "https://raw.githubusercontent.com/okkymabruri/priorityx/main/examples/bugs/bugs.csv"
 
@@ -15,7 +14,7 @@ df["date"] = df["reported_date"]
 temporal_granularity = "quarterly"
 entity_name = "Component"
 
-results, stats = fit_priority_matrix(
+results, stats = px.fit_priority_matrix(
     df,
     entity_col="component",
     timestamp_col="date",
@@ -28,7 +27,7 @@ print("Software Bug Priority Matrix:")
 print(results[["entity", "Random_Intercept", "Random_Slope", "count", "quadrant"]])
 
 # visualize
-plot_priority_matrix(
+px.plot_priority_matrix(
     results,
     entity_name=entity_name,
     show_quadrant_labels=True,

{priorityx-0.2.6 → priorityx-0.3.0}/examples/incidents/incident_monitoring.py

@@ -3,16 +3,7 @@
 
 import pandas as pd
 
-from priorityx.core.glmm import fit_priority_matrix
-from priorityx.tracking.movement import track_cumulative_movement
-from priorityx.tracking.transitions import extract_transitions
-from priorityx.tracking.drivers import (
-    extract_transition_drivers,
-    display_transition_drivers,
-)
-from priorityx.viz.matrix import plot_priority_matrix
-from priorityx.viz.timeline import plot_transition_timeline
-from priorityx.viz.trajectory import plot_entity_trajectories
+import priorityx as px
 from priorityx.utils.helpers import (
     display_quadrant_summary,
     display_transition_summary,
@@ -34,7 +25,7 @@ print("PRIORITY MATRIX ANALYSIS")
 
 temporal_granularity = "quarterly"
 entity_name = "Service"
-results, stats = fit_priority_matrix(
+results, stats = px.fit_priority_matrix(
     df,
     entity_col="service",
     timestamp_col="date",
@@ -49,7 +40,7 @@ print(results[["entity", "Random_Intercept", "Random_Slope", "count", "quadrant"
 display_quadrant_summary(results, entity_name=entity_name, min_count=0)
 
 # visualize
-plot_priority_matrix(
+px.plot_priority_matrix(
     results,
     entity_name=entity_name,
     show_quadrant_labels=True,
@@ -61,7 +52,7 @@ plot_priority_matrix(
 print()
 print("CUMULATIVE MOVEMENT TRACKING")
 
-movement, meta = track_cumulative_movement(
+movement, meta = px.track_cumulative_movement(
     df,
     entity_col="service",
     timestamp_col="date",
@@ -84,7 +75,7 @@ movement_path = save_dataframe_to_csv(
 print(f"Movement CSV saved: {movement_path}")
 
 # visualize entity trajectories
-plot_entity_trajectories(
+px.plot_entity_trajectories(
     movement,
     entity_name=entity_name,
     max_entities=5,
@@ -93,12 +84,12 @@ plot_entity_trajectories(
 )
 
 # detect transitions
-transitions = extract_transitions(movement, focus_risk_increasing=True)
+transitions = px.extract_transitions(movement, focus_risk_increasing=True)
 
 print(f"\nDetected {len(transitions)} risk-increasing transitions")
 display_transition_summary(transitions, entity_name=entity_name)
 
-plot_transition_timeline(
+px.plot_transition_timeline(
     transitions,
     entity_name=entity_name,
     save_plot=True,
@@ -129,7 +120,7 @@ if len(critical_transitions) > 0:
     )
 
     if prev_quarter:
-        driver_analysis = extract_transition_drivers(
+        driver_analysis = px.extract_transition_drivers(
             movement_df=movement,
             df_raw=df,
             entity_name=trans["entity"],
@@ -141,7 +132,7 @@ if len(critical_transitions) > 0:
             min_subcategory_delta=2,
         )
 
-        display_transition_drivers(driver_analysis)
+        px.display_transition_drivers(driver_analysis)
 
 print()
 print("Analysis complete. Check plot/ and results/ in the current working directory.")

{priorityx-0.2.6 → priorityx-0.3.0}/examples/violations/violations_monitoring.py

@@ -4,11 +4,7 @@ from datetime import datetime, timedelta
 
 import pandas as pd
 
-from priorityx.core.glmm import fit_priority_matrix
-from priorityx.tracking.movement import track_cumulative_movement
-from priorityx.tracking.transitions import extract_transitions
-from priorityx.viz.matrix import plot_priority_matrix
-from priorityx.viz.timeline import plot_transition_timeline
+import priorityx as px
 from priorityx.utils.helpers import (
     display_quadrant_summary,
     display_transition_summary,
@@ -64,7 +60,7 @@ df = pd.DataFrame(data)
 temporal_granularity = "quarterly"
 entity_name = "Department"
 
-results, stats = fit_priority_matrix(
+results, stats = px.fit_priority_matrix(
     df,
     entity_col="department",
     timestamp_col="date",
@@ -76,7 +72,7 @@ print(results[["entity", "Random_Intercept", "Random_Slope", "count", "quadrant"
 
 display_quadrant_summary(results, entity_name=entity_name, min_count=0)
 
-plot_priority_matrix(
+px.plot_priority_matrix(
     results,
     entity_name=entity_name,
     show_quadrant_labels=True,
@@ -84,7 +80,7 @@ plot_priority_matrix(
     save_csv=True,
 )
 
-movement, meta = track_cumulative_movement(
+movement, meta = px.track_cumulative_movement(
     df,
     entity_col="department",
     timestamp_col="date",
@@ -100,12 +96,12 @@ movement_path = save_dataframe_to_csv(
     temporal_granularity=temporal_granularity,
 )
 print(f"Movement CSV saved: {movement_path}")
-transitions = extract_transitions(movement, focus_risk_increasing=True)
+transitions = px.extract_transitions(movement, focus_risk_increasing=True)
 
 print(f"\nDetected {len(transitions)} risk-increasing transitions")
 display_transition_summary(transitions, entity_name=entity_name)
 
-plot_transition_timeline(
+px.plot_transition_timeline(
     transitions,
     entity_name=entity_name,
     save_plot=True,

{priorityx-0.2.6 → priorityx-0.3.0}/pyproject.toml

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

priorityx-0.3.0/src/priorityx/__init__.py

@@ -0,0 +1,43 @@
+"""priorityx: Entity prioritization and escalation detection using GLMM statistical models.
+
+The :mod:`priorityx.api` module exposes a small convenience facade so
+users can write::
+
+    import priorityx as px
+    results, stats = px.fit_priority_matrix(...)
+
+while more advanced workflows can continue to import from the
+``core``, ``tracking`` and ``viz`` subpackages directly.
+"""
+
+from .api import (  # noqa: F401
+    display_transition_drivers,
+    extract_transition_drivers,
+    extract_transitions,
+    fit,
+    fit_priority_matrix,
+    load_or_track_movement,
+    plot_entity_trajectories,
+    plot_priority_matrix,
+    plot_transition_timeline,
+    set_glmm_random_seed,
+    track_cumulative_movement,
+)
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "__version__",
+    "fit_priority_matrix",
+    "fit",
+    "set_glmm_random_seed",
+    "track_cumulative_movement",
+    "load_or_track_movement",
+    "extract_transitions",
+    "extract_transition_drivers",
+    "display_transition_drivers",
+    "plot_priority_matrix",
+    "plot_transition_timeline",
+    "plot_entity_trajectories",
+]
+

priorityx-0.3.0/src/priorityx/api.py

@@ -0,0 +1,41 @@
+"""Public convenience API for PriorityX.
+
+This module exposes the most commonly used functions via a compact
+namespace so users can write:
+
+    import priorityx as px
+    results, stats = px.fit_priority_matrix(...)
+
+without losing access to the more detailed submodules under
+``priorityx.core``, ``priorityx.tracking``, or ``priorityx.viz``.
+"""
+
+from .core.glmm import fit_priority_matrix, set_glmm_random_seed
+from .tracking.movement import track_cumulative_movement, load_or_track_movement
+from .tracking.transitions import extract_transitions
+from .tracking.drivers import (
+    extract_transition_drivers,
+    display_transition_drivers,
+)
+from .viz.matrix import plot_priority_matrix
+from .viz.timeline import plot_transition_timeline
+from .viz.trajectory import plot_entity_trajectories
+
+
+# Thin alias for the common GLMM fit path.
+fit = fit_priority_matrix
+
+
+__all__ = [
+    "fit_priority_matrix",
+    "fit",
+    "set_glmm_random_seed",
+    "track_cumulative_movement",
+    "load_or_track_movement",
+    "extract_transitions",
+    "extract_transition_drivers",
+    "display_transition_drivers",
+    "plot_priority_matrix",
+    "plot_transition_timeline",
+    "plot_entity_trajectories",
+]

{priorityx-0.2.6 → priorityx-0.3.0}/src/priorityx/core/glmm.py

@@ -9,9 +9,9 @@ import numpy as np
 import pandas as pd
 from statsmodels.genmod.bayes_mixed_glm import PoissonBayesMixedGLM
 
-# default priors (validated on regulatory data)
-DEFAULT_VCP_P = 3.5  # prior scale for random effects (higher = less shrinkage)
-DEFAULT_FE_P = 3.0  # prior scale for fixed effects
+# default prior scales for random and fixed effects
+DEFAULT_VCP_P = 3.5  # random effects prior scale
+DEFAULT_FE_P = 3.0  # fixed effects prior scale
 
 _ENV_VAR_NAME = "PRIORITYX_GLMM_SEED"
 _GLMM_RANDOM_SEED: Optional[int] = None

{priorityx-0.2.6 → priorityx-0.3.0}/src/priorityx/tracking/drivers.py

@@ -274,11 +274,13 @@ def extract_transition_drivers(
     including volume changes, growth changes, and contributing sub-categories.
 
     Args:
-        movement_df: Output from track_cumulative_movement()
+        movement_df: Output from track_cumulative_movement(). Expected to
+            contain the canonical period column ("quarter") whose labels
+            may be quarterly ("YYYY-QN") or monthly ("YYYY-MM").
         df_raw: Raw event data (pandas DataFrame)
         entity_name: Entity to analyze
-        quarter_from: Starting quarter (e.g., "2024-Q2")
-        quarter_to: Ending quarter (e.g., "2024-Q3")
+        quarter_from: Starting period label (e.g., "2024-Q2" or "2024-03")
+        quarter_to: Ending period label (e.g., "2024-Q3" or "2024-04")
         entity_col: Entity column name in df_raw
         timestamp_col: Timestamp column name in df_raw
         subcategory_cols: Optional list of subcategory columns to analyze
@@ -311,13 +313,14 @@ def extract_transition_drivers(
     df_raw[timestamp_col] = pd.to_datetime(df_raw[timestamp_col])
 
     # get transition data from movement_df
+    period_col = "quarter"
     entity_data = movement_df[movement_df["entity"] == entity_name]
 
     if len(entity_data) == 0:
         raise ValueError(f"Entity '{entity_name}' not found in movement data")
 
-    from_data = entity_data[entity_data["quarter"] == quarter_from]
-    to_data = entity_data[entity_data["quarter"] == quarter_to]
+    from_data = entity_data[entity_data[period_col] == quarter_from]
+    to_data = entity_data[entity_data[period_col] == quarter_to]
 
     if len(from_data) == 0:
         raise ValueError(f"Quarter '{quarter_from}' not found for '{entity_name}'")

{priorityx-0.2.6 → priorityx-0.3.0}/src/priorityx/tracking/transitions.py

@@ -99,15 +99,12 @@ def extract_transitions(
     1. Quadrant-to-quadrant transitions (Q3→Q2, Q2→Q1, etc.)
     2. Within-quadrant dramatic changes (velocity thresholds)
 
-    Key Innovation:
-    - Detects transitions from period_quadrant changes (actual movement)
-    - Classifies risk using global_quadrant (stable baseline)
-    - No oscillations in risk classification
-
     Args:
-        movement_df: DataFrame from track_cumulative_movement()
-                    Required columns: entity, quarter, period_quadrant,
-                    global_quadrant, period_x, period_y, x_delta, y_delta
+        movement_df: DataFrame from track_cumulative_movement(). Expected
+                    to contain the canonical period column (``quarter``)
+                    whose labels may be quarterly ("YYYY-QN") or monthly
+                    ("YYYY-MM"), plus: entity, period_quadrant,
+                    global_quadrant, period_x, period_y, x_delta, y_delta.
         focus_risk_increasing: Only return risk-increasing transitions (default: True)
                               If False, includes all transitions including improvements
 
@@ -132,9 +129,11 @@ def extract_transitions(
     """
     transitions = []
 
-    # group by entity and sort by quarter
+    period_col = "quarter"
+
+    # group by entity and sort by period
     for entity, entity_data in movement_df.groupby("entity"):
-        entity_data = entity_data.sort_values("quarter")
+        entity_data = entity_data.sort_values(period_col)
 
         # get global quadrant (stable across all periods)
         global_quad = entity_data.iloc[0]["global_quadrant"]
@@ -161,7 +160,7 @@ def extract_transitions(
                 transitions.append(
                     {
                         "entity": entity,
-                        "transition_quarter": next_row["quarter"],
+                        "transition_quarter": next_row[period_col],
                         "from_quadrant": from_quad,
                         "to_quadrant": to_quad,
                         "risk_level": risk_level,
@@ -181,8 +180,8 @@ def extract_transitions(
                 if growth_change > 1.0:
                     transitions.append(
                         {
-                            "entity": entity,
-                            "transition_quarter": next_row["quarter"],
+                        "entity": entity,
+                        "transition_quarter": next_row[period_col],
                             "from_quadrant": curr_row["period_quadrant"],
                             "to_quadrant": f"{next_row['period_quadrant']}*Y",  # *Y = growth spike
                             "risk_level": "critical",

{priorityx-0.2.6 → priorityx-0.3.0}/src/priorityx/viz/trajectory.py

@@ -71,22 +71,24 @@ def plot_entity_trajectories(
         print("No movement data to visualize")
         return None
 
-    # trim trajectories after last quarter with new events
+    period_col = "quarter"
+
+    # trim trajectories after last period 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()
+            last_active = active.groupby("entity")[period_col].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
+            # and cut them at their last active period
             df_trim = df_trim[
                 df_trim["last_active_quarter"].notna()
-                & (df_trim["quarter"] <= df_trim["last_active_quarter"])
+                & (df_trim[period_col] <= df_trim["last_active_quarter"])
             ]
             movement_df = df_trim
 
@@ -136,7 +138,7 @@ def plot_entity_trajectories(
 
     # plot trajectories for each entity
     for entity in entities_to_plot:
-        entity_data = df_plot[df_plot["entity"] == entity].sort_values("quarter")
+        entity_data = df_plot[df_plot["entity"] == entity].sort_values(period_col)
 
         if len(entity_data) < 2:
             continue
@@ -144,7 +146,7 @@ def plot_entity_trajectories(
         # use period coordinates for cumulative trajectory
         x = entity_data["period_x"].values
         y = entity_data["period_y"].values
-        quarters = entity_data["quarter"].values
+        quarters = entity_data[period_col].values
 
         # get color from global quadrant
         global_quad = entity_data.iloc[0]["global_quadrant"]