priorityx 0.1.2__tar.gz → 0.2.0__tar.gz

{priorityx-0.1.2 → priorityx-0.2.0}/Makefile

@@ -1,4 +1,8 @@
 # Version management for priorityx
+# Semantic versioning: MAJOR.MINOR.PATCH
+# - patch: bug fixes (0.1.1 -> 0.1.2)
+# - minor: new features, backward compatible (0.1.2 -> 0.2.0)
+# - major: breaking changes (0.2.0 -> 1.0.0)
 
 .PHONY: release release-patch release-minor release-major test
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: priorityx
-Version: 0.1.2
+Version: 0.2.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
@@ -9,7 +9,7 @@ Author-email: Okky Mabruri <okkymbrur@gmail.com>
 License: MIT
 License-File: LICENSE
 Keywords: escalation-detection,glmm,prioritization,risk-analysis,statistical-modeling
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
@@ -19,17 +19,23 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Requires-Dist: adjusttext>=1.3.0
 Requires-Dist: matplotlib>=3.9.4
 Requires-Dist: pandas>=2.3.3
-Requires-Dist: polars>=1.35.1
-Requires-Dist: pyarrow>=21.0.0
 Requires-Dist: statsmodels>=0.14.5
 Description-Content-Type: text/markdown
 
 # Priorityx: Entity prioritization and escalation detection using GLMM statistical models
 
+[![PyPI version](https://badge.fury.io/py/priorityx.svg)](https://badge.fury.io/py/priorityx)
+[![Downloads](https://static.pepy.tech/badge/priorityx)](https://pepy.tech/project/priorityx)
+[![Tests](https://github.com/okkymabruri/priorityx/workflows/Tests/badge.svg)](https://github.com/okkymabruri/priorityx/actions)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Entity prioritization and escalation detection using GLMM statistical models
+
 ## Installation
 
 ```bash
@@ -38,12 +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 tmp/complaints_analysis.py
+```
+
 ```python
-import polars as pl
+import pandas as pd
 from priorityx.core.glmm import fit_priority_matrix
 from priorityx.viz.matrix import plot_priority_matrix
 
-df = pl.read_csv("data.csv")
+df = pd.read_csv("data.csv")
 
 results, stats = fit_priority_matrix(
     df,
@@ -57,10 +71,10 @@ plot_priority_matrix(results, entity_name="Service", save_plot=True)
 
 ## Features
 
-- GLMM-based priority classification (Q1-Q4 quadrants)
-- Transition detection over time
-- Movement tracking
-- Visualization
+- 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
+- Deterministic seeding option for reproducible GLMM runs (set `PRIORITYX_GLMM_SEED`)
 
 ## Use Cases
 
@@ -70,4 +84,5 @@ IT incidents, software bugs, compliance violations, performance monitoring.
 
 - [Quick Start](docs/quickstart.md)
 - [API Reference](docs/api-reference.md)
-- [Methodology](docs/methodology.md)
+- [Methodology](docs/methodology.md)
+- [Priority Classification](docs/priority_classification.md)

priorityx-0.2.0/README.md

@@ -0,0 +1,60 @@
+# Priorityx: Entity prioritization and escalation detection using GLMM statistical models
+
+[![PyPI version](https://badge.fury.io/py/priorityx.svg)](https://badge.fury.io/py/priorityx)
+[![Downloads](https://static.pepy.tech/badge/priorityx)](https://pepy.tech/project/priorityx)
+[![Tests](https://github.com/okkymabruri/priorityx/workflows/Tests/badge.svg)](https://github.com/okkymabruri/priorityx/actions)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Entity prioritization and escalation detection using GLMM statistical models
+
+## Installation
+
+```bash
+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 tmp/complaints_analysis.py
+```
+
+```python
+import pandas as pd
+from priorityx.core.glmm import fit_priority_matrix
+from priorityx.viz.matrix import plot_priority_matrix
+
+df = pd.read_csv("data.csv")
+
+results, stats = fit_priority_matrix(
+    df,
+    entity_col="service",
+    timestamp_col="date",
+    temporal_granularity="quarterly"
+)
+
+plot_priority_matrix(results, entity_name="Service", save_plot=True)
+```
+
+## Features
+
+- 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
+- Deterministic seeding option for reproducible GLMM runs (set `PRIORITYX_GLMM_SEED`)
+
+## Use Cases
+
+IT incidents, software bugs, compliance violations, performance monitoring.
+
+## Documentation
+
+- [Quick Start](docs/quickstart.md)
+- [API Reference](docs/api-reference.md)
+- [Methodology](docs/methodology.md)
+- [Priority Classification](docs/priority_classification.md)

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

@@ -25,7 +25,7 @@ results, stats = fit_priority_matrix(
 Fits Poisson GLMM to classify entities into priority quadrants.
 
 **Parameters:**
-- `df`: polars DataFrame
+- `df`: pandas DataFrame
 - `entity_col`: Entity identifier column name
 - `timestamp_col`: Date column name
 - `count_col`: Count metric column (optional, defaults to row count)
@@ -41,6 +41,8 @@ Fits Poisson GLMM to classify entities into priority quadrants.
 - `results`: DataFrame with entity, Random_Intercept, Random_Slope, count, quadrant
 - `stats`: Dictionary with model statistics
 
+> **Reproducibility:** set the environment variable `PRIORITYX_GLMM_SEED` or call `set_glmm_random_seed(value)` before invoking `fit_priority_matrix` to obtain deterministic variational Bayes estimates.
+
 ---
 
 ## Tracking Functions
@@ -85,6 +87,60 @@ Extracts quadrant transitions from movement data.
 **Returns:**
 - DataFrame with transition details and risk levels
 
+### extract_transition_drivers
+
+```python
+from priorityx.tracking.drivers import extract_transition_drivers
+
+analysis = extract_transition_drivers(
+    movement_df,
+    df_raw,
+    entity_name="Service A",
+    quarter_from="2024-Q2",
+    quarter_to="2024-Q3",
+    entity_col="service",
+    timestamp_col="date",
+    subcategory_cols=["type", "category"],  # Optional
+    text_col="description"  # Optional
+)
+```
+
+Analyzes root causes of a quadrant transition.
+
+**Parameters:**
+- `movement_df`: Output from track_cumulative_movement()
+- `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")
+- `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
+
+**Returns:**
+- Dictionary with transition overview, magnitude metrics, subcategory drivers, keyword drivers, and priority classification
+
+### classify_priority
+
+```python
+from priorityx.tracking.drivers import classify_priority
+
+priority, reason, spike_axis = classify_priority(
+    from_quadrant="Q3",
+    to_quadrant="Q1",
+    x=0.5, y=0.6,
+    x_delta=0.5, y_delta=0.5,
+    count_delta=100,
+    percent_change=200
+)
+```
+
+Classifies supervisory priority (1=Critical, 2=Investigate, 3=Monitor, 4=Low).
+
+**Returns:**
+- Tuple of (priority, reason, spike_axis)
+
 ---
 
 ## Visualization Functions
@@ -118,18 +174,19 @@ fig = plot_transition_timeline(
     filter_risk_levels=["critical", "high"],
     max_entities=20,
     save_plot=False,
-    output_dir="plot"
+    output_dir="plot",
+    movement_df=movement_df
 )
 ```
 
-Creates timeline heatmap of transitions.
+Creates timeline heatmap of transitions. Passing `movement_df` is required to compute the Crisis/Investigate/Monitor/Low priority tiers and spike markers (`*X`, `*Y`, `*XY`). Omitting it falls back to legacy risk-level tags.
 
-### plot_movement_trajectories
+### plot_entity_trajectories
 
 ```python
-from priorityx.viz.trajectory import plot_movement_trajectories
+from priorityx.viz.trajectory import plot_entity_trajectories
 
-fig = plot_movement_trajectories(
+fig = plot_entity_trajectories(
     movement_df,
     entity_name="Entity",
     max_entities=10,
@@ -138,7 +195,7 @@ fig = plot_movement_trajectories(
 )
 ```
 
-Creates trajectory plot showing movement through priority space.
+Creates trajectory plot showing entity paths through priority space.
 
 ---
 
@@ -147,10 +204,29 @@ Creates trajectory plot showing movement through priority space.
 ### Display Summaries
 
 ```python
-from priorityx.utils.helpers import display_quadrant_summary, display_transition_summary
+from priorityx.utils.helpers import (
+    display_quadrant_summary,
+    display_transition_summary,
+    display_movement_summary
+)
 
 display_quadrant_summary(results_df, entity_name="Service")
 display_transition_summary(transitions_df, entity_name="Service")
+display_movement_summary(movement_df, entity_name="Service")
 ```
 
 Prints formatted summaries of analysis results.
+
+### display_transition_drivers
+
+```python
+from priorityx.tracking.drivers import display_transition_drivers
+
+display_transition_drivers(analysis, show_keywords=True)
+```
+
+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.1.2 → priorityx-0.2.0}/docs/methodology.md

@@ -29,7 +29,7 @@ count ~ time + seasonal_effects + (1 + time | entity)
 
 Entities classified based on random effects:
 
-**Q1 (Crisis):** intercept > 0, slope > 0, count ≥ 50
+**Q1 (Critical):** intercept > 0, slope > 0, count ≥ 50
 - High volume, accelerating growth
 - Requires immediate attention
 
@@ -45,7 +45,9 @@ Entities classified based on random effects:
 - High volume but not accelerating
 - Persistent baseline issues
 
-The count threshold for Q1 prevents low-volume entities from being mislabeled as Crisis.
+The count threshold for Q1 prevents low-volume entities from being mislabeled as Critical.
+
+Priority tiers applied in the transition timeline build on these quadrants with velocity-based rules (see `docs/priority_classification.md`) to differentiate Crisis, Investigate, Monitor, and Low responses.
 
 ## Movement Tracking
 

priorityx-0.2.0/docs/priority_classification.md

@@ -0,0 +1,41 @@
+# Priority Classification Overview
+
+A four-tier priority system ranks quadrant transitions by urgency using movement velocity, magnitude, and spike detection. Priorities are computed inside `plot_transition_timeline(..., movement_df=...)` and saved in transition CSVs.
+
+## Priority Tiers
+
+| Priority | Label & Color | Main Triggers | Recommended Action |
+|----------|---------------|---------------|--------------------|
+| **1 – Crisis** 🔴 | Explosion requiring immediate response | ΔX ≥ 0.40 or ΔY ≥ 0.40 (≈3σ); volume jump ≥ 50 with ≥500 % growth; both axes spiking (`*XY`) | Launch crisis playbook, staff war room, monitor daily |
+| **2 – Investigate** 🟠 | Rapid escalation needing urgent review | |ΔX > 0.15 or |ΔY > 0.15; entry into Q1 with strong position; ≥100 % growth with ≥5 new complaints | Trigger early warning, assign analysts, tighten monitoring cadence |
+| **3 – Monitor** 🟡 | Borderline movement worth watching | Position within ±0.10 of quadrant boundary; gentle Q1 entry | Track trend, document findings, review quarterly |
+| **4 – Low** 🟢 | Stable or improving | No conditions above met | Maintain routine oversight |
+
+## Spike Indicators
+
+| Marker | Meaning | Threshold |
+|--------|---------|-----------|
+| `*Y` | Growth spike | ΔY ≥ 0.40 |
+| `*X` | Volume spike | ΔX ≥ 0.40 |
+| `*XY` | Simultaneous spikes | ΔX ≥ 0.40 **and** ΔY ≥ 0.40 |
+
+## Threshold Reference
+
+| Metric | Cut-off | Notes |
+|--------|---------|-------|
+| Crisis spike | ±0.40 | ≈2.74σ, highlights extreme moves |
+| Velocity trigger | ±0.15 | Sustained acceleration worth investigation |
+| Growth shock | ≥100 % **and** ≥5 complaints | Filters out noise from tiny bases |
+| Explosion | ≥500 % **and** ≥50 complaints | High-volume surges escalated to Crisis |
+| Borderline band | ±0.10 | Used for Monitor prioritization |
+
+## Usage Guidelines
+
+1. **Always supply movement data**: `plot_transition_timeline(transitions, movement_df=movement)` is required for priority scoring; omitting it defaults to Priority 2.
+2. **Filter by priority**: e.g. `transitions[transitions["priority"] == 1]` to summarize crises; risk_level is retained for backward compatibility only.
+3. **Inspect spike markers**: `*X`, `*Y`, `*XY` signal urgent within-quadrant acceleration that may precede cross-quadrant jumps.
+4. **Adjust tracking range deliberately**: longer histories surface more transitions; short windows emphasize recent moves.
+
+## Changelog
+
+- **2024-11-09** – Introduced priority classification, spike markers, and timeline integration.

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

@@ -9,12 +9,13 @@ pip install priorityx
 ## Basic Usage
 
 ```python
-import polars as pl
+import pandas as pd
 from priorityx.core.glmm import fit_priority_matrix
 from priorityx.viz.matrix import plot_priority_matrix
 
 # load your data
-df = pl.read_csv("your_data.csv")
+df = pd.read_csv("your_data.csv")
+df["date"] = pd.to_datetime(df["date"])
 
 # fit priority matrix
 results, stats = fit_priority_matrix(
@@ -34,6 +35,7 @@ plot_priority_matrix(results, entity_name="Service", save_plot=True)
 ```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
 
 # track movement over time
@@ -49,6 +51,20 @@ transitions = extract_transitions(movement)
 
 # visualize transitions
 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(
+        movement_df=movement,
+        df_raw=df,
+        entity_name=first_transition["entity"],
+        quarter_from=first_transition["from_quarter"],
+        quarter_to=first_transition["transition_quarter"],
+        entity_col="service",
+        timestamp_col="date"
+    )
+    display_transition_drivers(analysis)
 ```
 
 ## Data Requirements
@@ -60,9 +76,8 @@ Your data needs:
 
 ## Output
 
-Results include:
-- Priority matrix: CSV + scatter plot
-- Transitions: CSV + timeline heatmap
-- Movement: CSV + trajectory plot
+By default, outputs saved to:
+- **`plot/`** - All PNG visualizations (priority matrix, transitions, trajectories)
+- **`results/`** - All CSV data files (entity scores, transitions, movement tracking)
 
-Outputs saved to `plot/` and `results/` directories.
+You can customize output directories using the `output_dir` parameter in visualization functions.

priorityx-0.2.0/examples/README.md

@@ -0,0 +1,36 @@
+# Examples
+
+These examples demonstrate priorityx usage with different datasets.
+
+## Prerequisites
+
+Install priorityx from PyPI:
+```bash
+pip install priorityx
+```
+
+Or install latest from source:
+```bash
+pip install git+https://github.com/okkymabruri/priorityx.git
+```
+
+## Running Examples
+
+**IT Incidents** (1,621 incidents, 10 services)
+```bash
+python examples/incidents/incident_monitoring.py
+```
+
+**Compliance Violations** (495 violations, 10 departments)
+```bash
+python examples/violations/violations_monitoring.py
+```
+
+**Software Bugs** (576 bugs, 10 components)
+Pre-generated CSV only. Use as input for your own analysis.
+
+## Output
+
+Results saved to:
+- `plot/` - Visualizations (PNG files)
+- `results/` - Data tables (CSV files)

priorityx-0.2.0/examples/bugs/bugs_monitoring.py

@@ -0,0 +1,41 @@
+# software bug tracking example
+
+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")
+
+# parse date column
+df["date"] = pd.to_datetime(df["reported_date"])
+
+# fit priority matrix
+temporal_granularity = "quarterly"
+entity_name = "Component"
+results, stats = fit_priority_matrix(
+    df,
+    entity_col="component",
+    timestamp_col="date",
+    temporal_granularity=temporal_granularity,
+    min_observations=4,
+)
+
+# display results
+print("Software Bug Priority Matrix:")
+print(results[["entity", "Random_Intercept", "Random_Slope", "count", "quadrant"]])
+
+# visualize
+plot_priority_matrix(
+    results,
+    entity_name=entity_name,
+    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/")
+
+# %%

priorityx-0.2.0/examples/incidents/incident_monitoring.py

@@ -0,0 +1,151 @@
+# it incident monitoring example
+
+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
+from priorityx.utils.helpers import (
+    display_quadrant_summary,
+    display_transition_summary,
+    save_dataframe_to_csv,
+)
+
+# load data
+df = pd.read_csv("examples/incidents/incidents.csv")
+df["date"] = pd.to_datetime(df["date"])
+
+print(f"Loaded {len(df)} incidents for {df['service'].nunique()} services")
+print(f"Date range: {df['date'].min()} to {df['date'].max()}")
+
+# fit priority matrix
+print()
+print("PRIORITY MATRIX ANALYSIS")
+
+temporal_granularity = "quarterly"
+entity_name = "Service"
+results, stats = fit_priority_matrix(
+    df,
+    entity_col="service",
+    timestamp_col="date",
+    temporal_granularity=temporal_granularity,
+    min_observations=8,
+    min_total_count=20,
+)
+
+print(f"\nAnalyzed {len(results)} services")
+print(results[["entity", "Random_Intercept", "Random_Slope", "count", "quadrant"]])
+
+display_quadrant_summary(results, entity_name=entity_name, min_count=0)
+
+# visualize
+plot_priority_matrix(
+    results,
+    entity_name=entity_name,
+    show_quadrant_labels=True,
+    save_plot=True,
+    save_csv=True,
+    output_dir="examples/incidents/plot",
+)
+
+# track movement
+print()
+print("CUMULATIVE MOVEMENT TRACKING")
+
+movement, meta = track_cumulative_movement(
+    df,
+    entity_col="service",
+    timestamp_col="date",
+    quarters=["2022-01-01", "2025-01-01"],
+    min_total_count=20,
+    temporal_granularity=temporal_granularity,
+)
+
+print(
+    f"\nTracked {meta['entities_tracked']} services over {meta['quarters_analyzed']} quarters"
+)
+
+# save movement
+movement_path = save_dataframe_to_csv(
+    movement,
+    artifact="trajectories",
+    entity_name=entity_name,
+    temporal_granularity=temporal_granularity,
+    output_dir="examples/incidents/results",
+)
+print(f"Movement CSV saved: {movement_path}")
+
+# visualize entity trajectories
+plot_entity_trajectories(
+    movement,
+    entity_name=entity_name,
+    max_entities=5,
+    save_plot=True,
+    save_csv=True,
+    output_dir="examples/incidents/plot",
+    results_dir="examples/incidents/results",
+)
+
+# detect transitions
+transitions = 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(
+    transitions,
+    entity_name=entity_name,
+    save_plot=True,
+    save_csv=True,
+    output_dir="examples/incidents/plot",
+    movement_df=movement,
+)
+
+critical_transitions = transitions[transitions["risk_level"] == "critical"]
+if len(critical_transitions) > 0:
+    trans = critical_transitions.iloc[0]
+
+    print()
+    print("DRIVER ANALYSIS EXAMPLE")
+    print(f"Analyzing: {trans['entity']}")
+    print(f"Transition: {trans['from_quadrant']} -> {trans['to_quadrant']}")
+    print(f"Quarter: {trans['transition_quarter']}")
+
+    entity_movement = (
+        movement[movement["entity"] == trans["entity"]]
+        .sort_values("quarter")
+        .reset_index(drop=True)
+    )
+    trans_idx = entity_movement[
+        entity_movement["quarter"] == trans["transition_quarter"]
+    ].index[0]
+    prev_quarter = (
+        entity_movement.loc[trans_idx - 1, "quarter"] if trans_idx > 0 else None
+    )
+
+    if prev_quarter:
+        driver_analysis = extract_transition_drivers(
+            movement_df=movement,
+            df_raw=df,
+            entity_name=trans["entity"],
+            quarter_from=prev_quarter,
+            quarter_to=trans["transition_quarter"],
+            entity_col="service",
+            timestamp_col="date",
+        )
+
+        display_transition_drivers(driver_analysis)
+
+print()
+print(
+    "Analysis complete. Check examples/incidents/plot/ and examples/incidents/results/"
+)
+
+# %%