priorityx 0.3.0__tar.gz → 0.5.0__tar.gz

priorityx-0.5.0/.github/workflows/docs.yml

@@ -0,0 +1,31 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: pip install mkdocs mkdocs-material pymdown-extensions
+
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

{priorityx-0.3.0 → priorityx-0.5.0}/.github/workflows/release.yml

@@ -13,7 +13,7 @@ jobs:
     name: Build package
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v6
 
     - name: Set up Python
       uses: actions/setup-python@v6
@@ -87,7 +87,7 @@ jobs:
       contents: write
 
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v6
 
     - name: Create Release
       uses: softprops/action-gh-release@v2

{priorityx-0.3.0 → priorityx-0.5.0}/.github/workflows/test.yml

@@ -14,7 +14,7 @@ jobs:
         python-version: ['3.10', '3.11', '3.12']
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
       - uses: actions/setup-python@v6
         with:

priorityx-0.5.0/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+Only major releases (v0.x.0) are listed.
+
+---
+
+## v0.4.0 (2025-01)
+
+**Unified API with Axis Metrics**
+
+- Introduced `x_metric` / `y_metric` parameters to `fit_priority_matrix()` for flexible axis definitions beyond default volume/growth
+- Added `x_score` / `y_score` coordinate-based quadrant classification (replaces Random_Intercept/Random_Slope naming in outputs)
+- Added Gamma family support for continuous GLMM (e.g., duration or amount metrics)
+- Gaussian GLMM support for metric-based axes
+- Improved quadrant label rendering with configurable legend position (`legend_loc`, `show_legend`)
+- Row-aligned quadrant label offsetting to avoid legend overlap
+
+**Trajectory Auto-Selection**
+
+- Added `highlight_top_n` parameter to `plot_entity_trajectories()` for automatic entity selection
+- Added `highlight_by` parameter: `"trajectory_distance"` (euclidean path) or `"total_movement"` (manhattan)
+- Added `recent_periods` parameter to limit trajectory window to last N periods
+
+**Enhanced Driver Analysis**
+
+- Added `numeric_cols` parameter to `extract_transition_drivers()` for amount/duration breakdowns
+  - Explicit bins: `{"amount": [0, 1e6, 5e6, 10e6]}`
+  - Auto quantiles: `{"duration": 4}` (4 bins)
+- Renamed `quarter_from`/`quarter_to` to `period_from`/`period_to` (backwards compatible)
+- Renamed `top_n_subcategories` to `top_n`, `min_subcategory_delta` to `min_delta` (backwards compatible)
+- Added `save_txt`, `txt_path`, `txt_mode` parameters to `display_transition_drivers()` for file output
+
+---
+
+## v0.3.0 (2024-12)
+
+**Entity Metrics and Priority Indices**
+
+- Implemented `add_priority_indices()` for composite index calculation:
+  - **RI** (Risk Index): volume + growth + severity
+  - **SQI** (Service Quality Index): resolution speed + recovery rate
+  - **EWI** (Early Warning Index): blends RI and SQI for prioritization
+- Added `aggregate_entity_metrics()` helper for per-entity metric aggregation
+- Added `sensitivity_analysis()` for weight stability testing
+- Monthly granularity support (beta) in GLMM and visualizations
+- Unified `px.*` namespace imports pattern
+
+---
+
+## v0.2.0 (2024-11)
+
+**Transition Tracking and Visualization**
+
+- Implemented `track_cumulative_movement()` for entity trajectory tracking
+- Added `extract_transitions()` for quadrant movement detection
+- Transition timeline visualization with priority-based coloring (Crisis/Investigate/Monitor/Low)
+- Spike markers (`*X`, `*Y`, `*XY`) for volume/growth spikes
+- Deterministic seeding via `PRIORITYX_GLMM_SEED` for reproducible GLMM fits
+- `plot_entity_trajectories()` for movement path visualization
+- Transition driver analysis (experimental)
+
+---
+
+## v0.1.0 (2024-10)
+
+**Initial Release**
+
+- Core GLMM estimation with Poisson mixed effects (statsmodels backend)
+- `fit_priority_matrix()` main API for entity prioritization
+- Quadrant classification (Q1-Q4) based on volume and growth
+- Priority matrix scatter plot visualization
+- Quarterly, yearly, and semiannual temporal granularity
+- Date filtering and minimum observation thresholds
+- CSV and plot export with configurable output directories

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: priorityx
-Version: 0.3.0
+Version: 0.5.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.5.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.5.0/docs/api-reference.md

@@ -0,0 +1,407 @@
+# API Reference
+
+## Core Functions
+
+### fit_priority_matrix
+
+```python
+import priorityx as px
+
+# Default: volume × 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
+
+# Custom Y axis: volume × resolution_days (two GLMMs)
+results, stats = px.fit_priority_matrix(
+    df,
+    entity_col="service",
+    timestamp_col="date",
+    y_metric="resolution_days",
+)
+
+# Custom both axes with Gamma family for right-skewed data
+results, stats = px.fit_priority_matrix(
+    df,
+    entity_col="service",
+    timestamp_col="date",
+    x_metric="disputed_amount",
+    y_metric="paid_amount",
+    family="gamma",
+)
+```
+
+Unified entry point for GLMM-based entity prioritization. Supports count-based (Poisson) and metric-based (Gaussian/Gamma) axes.
+
+**Parameters:**
+
+- `df`: pandas DataFrame with one row per event
+- `entity_col`: Entity identifier column name
+- `timestamp_col`: Date column name
+- `x_metric`: Optional metric column for X axis (None = count-based)
+- `y_metric`: Optional metric column for Y axis (None = count-based)
+- `x_effect`: Random effect for X score ("intercept" or "slope", default: "intercept")
+- `y_effect`: Random effect for Y score ("intercept" or "slope", default: "slope")
+- `family`: Distribution for continuous metrics ("gaussian" or "gamma", default: "gaussian")
+- `count_col`: Optional count column (default: row count per entity-period)
+- `date_filter`: Date filter string (e.g., "< 2025-01-01", ">= 2024-01-01")
+- `min_observations`: Minimum time periods required per entity
+- `min_total_count`: Minimum total count threshold
+- `decline_window_quarters`: Filter entities inactive >N quarters
+- `temporal_granularity`: "yearly", "quarterly", "semiannual", or "monthly"
+- `vcp_p`: Random effects prior scale (default: 3.5)
+- `fe_p`: Fixed effects prior scale (default: 3.0)
+
+**Returns:**
+
+- `results`: DataFrame with `entity`, `x_score`, `y_score`, `count`, `quadrant`
+- `stats`: Dictionary with model statistics
+
+**Family Selection:**
+
+- `"gaussian"` (default): Works for any data, robust for entity ranking
+- `"gamma"`: Use for right-skewed positive data (durations, monetary amounts)
+
+> **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.
+
+---
+
+## Metrics Functions
+
+### aggregate_entity_metrics
+
+```python
+import priorityx as px
+
+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",
+)
+# Returns: entity, mean_duration, total_primary, total_secondary, secondary_to_primary_ratio
+```
+
+Computes per-entity aggregated metrics for enrichment.
+
+### add_priority_indices
+
+```python
+import priorityx as px
+
+enriched = 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",
+    # Weights (defaults 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,
+)
+```
+
+Adds composite risk indices to enriched entity data.
+
+**Output columns:**
+
+- `z_volume`, `z_growth`, `z_severity`: Z-scored risk components
+- `z_neg_resolution`, `z_recovery`: Z-scored quality components
+- `RI`: Risk Index = weighted sum of z_volume, z_growth, z_severity
+- `SQI`: Service Quality Index = weighted sum of z_neg_resolution, z_recovery
+- `EWI`: Early Warning Index = w_risk × RI + w_quality × (-SQI)
+
+**Usage:**
+```python
+# Top priority entities
+top_risks = enriched.nlargest(10, "EWI")
+```
+
+### sensitivity_analysis
+
+```python
+import priorityx as px
+
+results = px.sensitivity_analysis(
+    df,
+    index_col="EWI",
+    entity_col="entity",
+    weight_ranges={
+        "w_risk": [0.6, 0.7, 0.8],
+        "w_quality": [0.2, 0.3, 0.4],
+    },
+    top_n=10,
+)
+```
+
+Tests ranking stability across weight variations.
+
+---
+
+## Tracking Functions
+
+### track_cumulative_movement
+
+```python
+import priorityx as px
+
+movement, meta = px.track_cumulative_movement(
+    df,
+    entity_col,
+    timestamp_col,
+    quarters=None,
+    min_total_count=20,
+    decline_window_quarters=6,
+    temporal_granularity="quarterly",
+    vcp_p=3.5,
+    fe_p=3.0
+)
+```
+
+Tracks entity movement through priority quadrants over time.
+
+**Returns:**
+
+- `movement`: DataFrame with quarterly X/Y positions
+- `meta`: Dictionary with tracking metadata
+
+### extract_transitions
+
+```python
+import priorityx as px
+
+transitions = px.extract_transitions(
+    movement_df,
+    focus_risk_increasing=True
+)
+```
+
+Extracts quadrant transitions from movement data.
+
+**Returns:**
+
+- DataFrame with transition details and risk levels
+
+### extract_transition_drivers
+
+```python
+import priorityx as px
+
+# Basic usage with categorical breakdowns
+analysis = px.extract_transition_drivers(
+    movement_df,
+    df_raw,
+    entity_name="Service A",
+    period_from="2024-Q2",
+    period_to="2024-Q3",
+    entity_col="service",
+    timestamp_col="date",
+    subcategory_cols=["type", "category"],  # categorical breakdowns
+)
+
+# With numeric column breakdowns (amounts, durations)
+analysis = px.extract_transition_drivers(
+    movement_df,
+    df_raw,
+    entity_name="Fintech - Pinjaman Online",
+    period_from="2024-Q3",
+    period_to="2024-Q4",
+    entity_col="product",
+    timestamp_col="date",
+    subcategory_cols=["region", "gender"],
+    numeric_cols={
+        "disputed_amount": [0, 1e6, 5e6, 10e6],  # explicit bin edges
+        "resolution_days": 4,                     # 4 quantile bins (auto)
+    },
+)
+```
+
+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
+- `period_from`: Starting period (e.g., "2024-Q2", "2024-01")
+- `period_to`: Ending period (e.g., "2024-Q3", "2024-02")
+- `entity_col`: Entity column name
+- `timestamp_col`: Timestamp column name
+- `subcategory_cols`: Optional list of categorical columns for breakdown (auto-detected when omitted)
+- `numeric_cols`: Optional dict of numeric columns with bin specs:
+  - List of floats: explicit bin edges (e.g., `[0, 1e6, 5e6, 10e6]`)
+  - Integer: number of quantile bins (e.g., `4` for quartiles)
+- `top_n`: Limit of drivers per column (default: 3)
+- `min_delta`: Minimum count delta for inclusion (default: 1)
+
+**Returns:**
+
+- 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 for categorical columns
+  - `numeric_drivers`: per-column driver lists for numeric columns (with bin edges)
+  - `priority`: priority tier, trigger reason, spike axis
+  - `meta`: diagnostic flags (e.g., whether subcategory columns were auto-detected)
+
+### 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
+
+### plot_priority_matrix
+
+```python
+import priorityx as px
+
+fig = px.plot_priority_matrix(
+    results_df,
+    entity_name="Entity",
+    figsize=(16, 12),
+    top_n_labels=5,
+    show_quadrant_labels=False,
+    save_plot=False,
+    output_dir="plot"
+)
+```
+
+Creates scatter plot of priority matrix.
+
+### plot_transition_timeline
+
+```python
+import priorityx as px
+
+fig = px.plot_transition_timeline(
+    transitions_df,
+    entity_name="Entity",
+    filter_risk_levels=["critical", "high"],
+    max_entities=20,
+    save_plot=False,
+    output_dir="plot",
+    movement_df=movement_df
+)
+```
+
+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_entity_trajectories
+
+```python
+import priorityx as px
+
+# Basic usage
+fig = px.plot_entity_trajectories(
+    movement_df,
+    entity_name="Entity",
+    max_entities=10,
+    save_plot=False,
+    plot_dir="plot"
+)
+
+# Auto-select top movers (recommended)
+fig = px.plot_entity_trajectories(
+    movement_df,
+    entity_name="product",
+    highlight_top_n=4,                   # auto-select top 4 entities
+    highlight_by="trajectory_distance",  # by path length (or "total_movement")
+    recent_periods=6,                    # limit to last 6 periods
+    save_plot=True,
+    plot_dir="results/plot",
+)
+```
+
+Creates trajectory plot showing entity paths through priority space.
+
+**Parameters:**
+
+- `movement_df`: Output from track_cumulative_movement()
+- `entity_name`: Label for entity type (e.g., "product", "service")
+- `max_entities`: Maximum entities to show (default: 10)
+- `highlight_entities`: List of specific entities to highlight
+- `highlight_top_n`: Auto-select top N entities by movement (overrides max_entities)
+- `highlight_by`: Selection method when using highlight_top_n:
+  - `"trajectory_distance"`: Euclidean path length (sum of sqrt(dx² + dy²))
+  - `"total_movement"`: Manhattan distance (sum of |dx| + |dy|)
+- `recent_periods`: Limit trajectory to last N periods (useful for long histories)
+- `temporal_granularity`: "quarterly", "monthly", etc.
+- `save_plot`: Save to file (default: False)
+- `save_csv`: Save trajectory data to CSV (default: False)
+- `plot_dir`: Output directory for plots
+- `csv_dir`: Output directory for CSVs
+- `close_fig`: Close figure after rendering (set True for Jupyter to avoid duplicates)
+
+---
+
+## Utility Functions
+
+### Display Summaries
+
+```python
+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
+import priorityx as px
+
+# Print to console
+px.display_transition_drivers(analysis)
+
+# Print and save to file
+px.display_transition_drivers(
+    analysis,
+    save_txt=True,
+    txt_path="driver_analysis.txt",
+    txt_mode="a",  # append (default) or "w" to overwrite
+)
+```
+
+Prints transition driver analysis in human-readable format.
+
+**Parameters:**
+
+- `analysis`: Output from extract_transition_drivers()
+- `save_txt`: Save output to text file (default: False)
+- `txt_path`: Path for text file (required if save_txt=True)
+- `txt_mode`: File mode - "a" to append (default), "w" to overwrite