priorityx 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: priorityx
-Version: 0.3.0
+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
@@ -50,16 +50,71 @@ 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

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

@@ -22,16 +22,71 @@ 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

{priorityx-0.3.0 → 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.3.0 → priorityx-0.4.0}/pyproject.toml

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

{priorityx-0.3.0 → priorityx-0.4.0}/src/priorityx/__init__.py

@@ -8,13 +8,29 @@ users can write::
 
 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,
     fit_priority_matrix,
     load_or_track_movement,
     plot_entity_trajectories,
@@ -24,20 +40,25 @@ from .api import (  # noqa: F401
     track_cumulative_movement,
 )
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 __all__ = [
     "__version__",
+    # Core - ONE fitting function
     "fit_priority_matrix",
-    "fit",
+    # 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.3.0 → priorityx-0.4.0}/src/priorityx/api.py

@@ -11,6 +11,7 @@ without losing access to the more detailed submodules under
 """
 
 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 (
@@ -22,13 +23,12 @@ 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
-
-
+# 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",
-    "fit",
+    # Tracking and visualization helpers
     "set_glmm_random_seed",
     "track_cumulative_movement",
     "load_or_track_movement",
@@ -38,4 +38,8 @@ __all__ = [
     "plot_priority_matrix",
     "plot_transition_timeline",
     "plot_entity_trajectories",
+    # Metrics
+    "aggregate_entity_metrics",
+    "add_priority_indices",
+    "sensitivity_analysis",
 ]