priorityx 0.2.5__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: priorityx
-Version: 0.2.5
+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.5 → 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.3.0/docs/README.md

@@ -0,0 +1,15 @@
+# Docs overview
+
+This folder holds the main reference material for `priorityx`.
+
+- `quickstart.md` – short walk‑through: install, load data, run a first
+  priority matrix and plot it.
+- `api-reference.md` – function‑by‑function notes for the core modules
+  (GLMM, movement, transitions, plots, helpers).
+- `methodology.md` – background on the modelling choices: Poisson GLMM,
+  time aggregation, movement tracking, and how we think about risk
+  quadrants.
+- `priority_classification.md` – how P1–P4 priorities and spike markers
+  are defined and used in timelines.
+ - `output_naming.md` – how plot/CSV artifacts are named and where they
+   are written on disk (e.g. `results/plot`, `results/csv`).

{priorityx-0.2.5 → 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.3.0/docs/output_naming.md

@@ -0,0 +1,168 @@
+% PriorityX Output Naming
+
+This note documents where PriorityX writes plots/CSVs and how filenames
+are constructed. It is meant as a quick reference when wiring outputs
+into EWS pipelines or BI tools.
+
+---
+
+## Directories
+
+By default, PriorityX writes artifacts under the current working
+directory, using two main folders:
+
+- `results/plot/` – PNG plots
+- `results/csv/` – CSV tables (movement, matrices, transitions, etc.)
+
+You can override these via the `plot_dir` / `csv_dir` / `output_dir`
+arguments on the plotting and helper functions.
+
+---
+
+## Priority Matrix
+
+Function: `priorityx.viz.matrix.plot_priority_matrix`
+
+- Default `plot_dir`: `results/plot`
+- Default `csv_dir`: `results/csv`
+- Filename pattern (plot):
+
+  ```text
+  priority_matrix-<entity_name_slug>-<granularity_suffix>-<YYYYMMDD>.png
+  ```
+
+- Filename pattern (CSV):
+
+  ```text
+  priority_matrix-<entity_name_slug>-<granularity_suffix>-<YYYYMMDD>.csv
+  ```
+
+Where:
+
+- `<entity_name_slug>` is `entity_name.lower().replace(" ", "_")`
+- `<granularity_suffix>` is:
+  - `Q` for quarterly
+  - `Y` for yearly
+  - `S` for semiannual
+
+Example (topics, quarterly):
+
+```text
+results/plot/priority_matrix-topic-Q-20251126.png
+results/csv/priority_matrix-topic-Q-20251126.csv
+```
+
+---
+
+## Transition Timelines
+
+Function: `priorityx.viz.timeline.plot_transition_timeline`
+
+- Default `plot_dir`: `results/plot`
+- Default `csv_dir`: `results/csv`
+- Filename pattern (plot):
+
+  ```text
+  transition_timeline-<entity_name_slug>-<granularity_suffix>-<YYYYMMDD>.png
+  ```
+
+- Filename pattern (CSV):
+
+  ```text
+  transition_timeline-<entity_name_slug>-<granularity_suffix>-<YYYYMMDD>.csv
+  ```
+
+Example (FSPs, quarterly):
+
+```text
+results/plot/transition_timeline-fsp-Q-20251126.png
+results/csv/transition_timeline-fsp-Q-20251126.csv
+```
+
+---
+
+## Trajectories
+
+Function: `priorityx.viz.trajectory.plot_entity_trajectories`
+
+- Default `plot_dir`: `results/plot`
+- Default `csv_dir`: `results/csv`
+- Filename pattern (plot):
+
+  ```text
+  trajectories-<entity_name_slug>-<granularity_suffix>-<YYYYMMDD>.png
+  ```
+
+- When `save_csv=True` (default is `False`), CSV is saved via
+  `priorityx.utils.helpers.save_dataframe_to_csv` with artifact name
+  `"trajectories"` (see next section).
+
+Example (topics, quarterly):
+
+```text
+results/plot/trajectories-topic-Q-20251126.png
+results/csv/trajectories-topic-Q-20251126.csv   # only when save_csv=True
+```
+
+---
+
+## Helpers: CSV Naming
+
+Utility: `priorityx.utils.helpers.save_dataframe_to_csv`
+
+This helper centralises CSV naming using `generate_output_path`:
+
+```text
+<output_dir>/<artifact>-<entity_slug>-<granularity_suffix>-<YYYYMMDD>.csv
+```
+
+Where:
+
+- `<output_dir>` defaults to `results/csv`
+- `<artifact>` is a short key such as `movement`, `trajectories`,
+  `priority_matrix`
+- `<entity_slug>` is `entity_name.lower().replace(" ", "_")`
+- `<granularity_suffix>` is `Q`, `Y`, or `S` (as above)
+
+Examples:
+
+```text
+results/csv/movement-topic-Q-20251126.csv
+results/csv/trajectories-fsp-Q-20251126.csv
+```
+
+### EWS canonical CSV outputs
+
+For the complaints Early Warning System (EWS) pipelines, the canonical
+CSV artifacts per run are:
+
+```text
+movement-*.csv
+priority_matrix-*.csv
+transitions-*.csv
+```
+
+Trajectory CSVs (`trajectories-*.csv`) are optional and are typically
+only written for selected custom views (for example, a focus list of
+FSPs or products) by explicitly passing `save_csv=True` to
+`plot_entity_trajectories`.
+
+---
+
+## Overriding locations
+
+All plotting and helper functions accept directories as keyword
+arguments (`plot_dir`, `csv_dir`, `output_dir`). To write outputs into a
+custom EWS workspace, pass explicit paths, for example:
+
+```python
+plot_priority_matrix(
+    results_df,
+    entity_name="Topic",
+    plot_dir="ews/results/plot",
+    csv_dir="ews/results/csv",
+)
+```
+
+This keeps file naming consistent while letting each project choose
+where artifacts live.

{priorityx-0.2.5 → 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.5 → 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.5 → priorityx-0.3.0}/examples/incidents/incident_monitoring.py

@@ -3,24 +3,15 @@
 
 import pandas as pd
 
-RAW_DATA_URL = "https://raw.githubusercontent.com/okkymabruri/priorityx/main/examples/incidents/incidents.csv"
-
-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,
     save_dataframe_to_csv,
 )
 
+RAW_DATA_URL = "https://raw.githubusercontent.com/okkymabruri/priorityx/main/examples/incidents/incidents.csv"
+
 # load data from GitHub raw
 df = pd.read_csv(RAW_DATA_URL, parse_dates=["date"])
 print("Loaded incidents from GitHub raw URL")
@@ -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.5 → 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.5 → priorityx-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "priorityx"
-version = "0.2.5"
+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",
+]
+