priorityx 0.2.6__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: priorityx
-Version: 0.2.6
+Version: 0.4.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,75 @@ pip install priorityx
 
 ## Quick Start
 
-### Deterministic runs
+```python
+import pandas as pd
+import priorityx as px
 
-Set `PRIORITYX_GLMM_SEED` (or call `set_glmm_random_seed()`) before running analyses to obtain repeatable GLMM estimates during debugging or CI checks:
+df = pd.read_csv("data.csv")
 
-```bash
-PRIORITYX_GLMM_SEED=1234 python your_script.py
+# Default: volume x growth (single GLMM)
+results, stats = px.fit_priority_matrix(
+    df,
+    entity_col="service",
+    timestamp_col="date",
+    temporal_granularity="quarterly",
+)
+# Returns: entity, x_score, y_score, count, quadrant
+
+px.plot_priority_matrix(results, entity_name="Service", save_plot=True)
 ```
 
-```python
-import pandas as pd
-from priorityx.core.glmm import fit_priority_matrix
-from priorityx.viz.matrix import plot_priority_matrix
+### Custom Axes
 
-df = pd.read_csv("data.csv")
+```python
+# Custom Y axis: volume × resolution_days (two GLMMs)
+results, _ = px.fit_priority_matrix(
+    df,
+    entity_col="service",
+    timestamp_col="date",
+    y_metric="resolution_days",
+)
 
-results, stats = fit_priority_matrix(
+# Custom both axes: disputed_amount × paid_amount
+results, _ = px.fit_priority_matrix(
     df,
     entity_col="service",
     timestamp_col="date",
-    temporal_granularity="quarterly"
+    x_metric="disputed_amount",
+    y_metric="paid_amount",
+)
+```
+
+### Composite Indices
+
+```python
+# Add entity metrics
+metrics = px.aggregate_entity_metrics(
+    df,
+    entity_col="service",
+    duration_start_col="opened_at",
+    duration_end_col="closed_at",
+    primary_col="exposure",
+    secondary_col="recovery",
+)
+results = results.merge(metrics, left_on="entity", right_on="service", how="left")
+
+# Add weighted indices: RI (Risk), SQI (Service Quality), EWI (Early Warning)
+results = px.add_priority_indices(
+    results,
+    volume_col="count",
+    growth_col="y_score",
+    severity_col="total_primary",
+    resolution_col="mean_duration",
+    recovery_col="secondary_to_primary_ratio",
+    # customize weights (default shown)
+    w_volume=0.4, w_growth=0.4, w_severity=0.2,
+    w_resolution=0.5, w_recovery=0.5,
+    w_risk=0.7, w_quality=0.3,
 )
 
-plot_priority_matrix(results, entity_name="Service", save_plot=True)
+# Top priority entities
+top_risks = results.nlargest(10, "EWI")
 ```
 
 ## Features

priorityx-0.4.0/README.md

@@ -0,0 +1,107 @@
+# 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
+
+```python
+import pandas as pd
+import priorityx as px
+
+df = pd.read_csv("data.csv")
+
+# Default: volume x growth (single GLMM)
+results, stats = px.fit_priority_matrix(
+    df,
+    entity_col="service",
+    timestamp_col="date",
+    temporal_granularity="quarterly",
+)
+# Returns: entity, x_score, y_score, count, quadrant
+
+px.plot_priority_matrix(results, entity_name="Service", save_plot=True)
+```
+
+### Custom Axes
+
+```python
+# Custom Y axis: volume × resolution_days (two GLMMs)
+results, _ = px.fit_priority_matrix(
+    df,
+    entity_col="service",
+    timestamp_col="date",
+    y_metric="resolution_days",
+)
+
+# Custom both axes: disputed_amount × paid_amount
+results, _ = px.fit_priority_matrix(
+    df,
+    entity_col="service",
+    timestamp_col="date",
+    x_metric="disputed_amount",
+    y_metric="paid_amount",
+)
+```
+
+### Composite Indices
+
+```python
+# Add entity metrics
+metrics = px.aggregate_entity_metrics(
+    df,
+    entity_col="service",
+    duration_start_col="opened_at",
+    duration_end_col="closed_at",
+    primary_col="exposure",
+    secondary_col="recovery",
+)
+results = results.merge(metrics, left_on="entity", right_on="service", how="left")
+
+# Add weighted indices: RI (Risk), SQI (Service Quality), EWI (Early Warning)
+results = px.add_priority_indices(
+    results,
+    volume_col="count",
+    growth_col="y_score",
+    severity_col="total_primary",
+    resolution_col="mean_duration",
+    recovery_col="secondary_to_primary_ratio",
+    # customize weights (default shown)
+    w_volume=0.4, w_growth=0.4, w_severity=0.2,
+    w_resolution=0.5, w_recovery=0.5,
+    w_risk=0.7, w_quality=0.3,
+)
+
+# Top priority entities
+top_risks = results.nlargest(10, "EWI")
+```
+
+## 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
+- 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
+
+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.2.6 → priorityx-0.4.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.4.0}/docs/priority_classification.md

@@ -7,7 +7,7 @@ A four-tier priority system ranks quadrant transitions by urgency using movement
 | 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 |
+| **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 |
 

{priorityx-0.2.6 → priorityx-0.4.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.4.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.4.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.4.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.4.0}/pyproject.toml

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

priorityx-0.4.0/src/priorityx/__init__.py

@@ -0,0 +1,64 @@
+"""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.
+
+## current version API (consolidated)
+
+The unified API uses ``fit_priority_matrix()`` as THE single entry point:
+
+    # Default: volume x growth
+    results, stats = px.fit_priority_matrix(df, entity_col="service", timestamp_col="date")
+
+    # Custom Y axis: volume x resolution_days
+    results, stats = px.fit_priority_matrix(df, ..., y_metric="resolution_days")
+
+    # Custom both axes: disputed x paid
+    results, stats = px.fit_priority_matrix(df, ..., x_metric="disputed", y_metric="paid")
+
+Return columns: entity, x_score, y_score, count, quadrant
+"""
+
+from .api import (  # noqa: F401
+    aggregate_entity_metrics,
+    add_priority_indices,
+    display_transition_drivers,
+    extract_transition_drivers,
+    extract_transitions,
+    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.4.0"
+
+__all__ = [
+    "__version__",
+    # Core - ONE fitting function
+    "fit_priority_matrix",
+    # Utilities
+    "set_glmm_random_seed",
+    # Tracking
+    "track_cumulative_movement",
+    "load_or_track_movement",
+    "extract_transitions",
+    "extract_transition_drivers",
+    "display_transition_drivers",
+    # Visualization
+    "plot_priority_matrix",
+    "plot_transition_timeline",
+    "plot_entity_trajectories",
+    # Metrics
+    "aggregate_entity_metrics",
+    "add_priority_indices",
+]

priorityx-0.4.0/src/priorityx/api.py

@@ -0,0 +1,45 @@
+"""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 .metrics import aggregate_entity_metrics, add_priority_indices, sensitivity_analysis
+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
+
+
+# Public facade exports - current version API (consolidated)
+# Removed: fit(), fit_axes(), fit_priority_axes() - use fit_priority_matrix() with x_metric/y_metric
+__all__ = [
+    # Core GLMM entrypoint - THE single fitting function
+    "fit_priority_matrix",
+    # Tracking and visualization helpers
+    "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",
+    # Metrics
+    "aggregate_entity_metrics",
+    "add_priority_indices",
+    "sensitivity_analysis",
+]