priorityx 0.2.5__tar.gz → 0.2.6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: priorityx
-Version: 0.2.5
+Version: 0.2.6
 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

priorityx-0.2.6/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.6/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.2.6}/pyproject.toml

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

{priorityx-0.2.5 → priorityx-0.2.6}/src/priorityx/__init__.py

@@ -1,6 +1,6 @@
 """priorityx: Entity prioritization and escalation detection using GLMM statistical models."""
 
-__version__ = "0.2.5"
+__version__ = "0.2.6"
 
 # API will be imported
 

{priorityx-0.2.5 → priorityx-0.2.6}/src/priorityx/core/glmm.py

@@ -69,7 +69,7 @@ def fit_priority_matrix(
     min_observations: int = 3,
     min_total_count: int = 0,
     decline_window_quarters: int = 6,
-    temporal_granularity: Literal["yearly", "quarterly", "semiannual"] = "yearly",
+    temporal_granularity: Literal["yearly", "quarterly", "semiannual", "monthly"] = "yearly",
     vcp_p: float = DEFAULT_VCP_P,
     fe_p: float = DEFAULT_FE_P,
     verbose: bool = False,
@@ -215,6 +215,25 @@ def fit_priority_matrix(
                 .sort_values(["year", "semester", entity_col])
             )
 
+    elif temporal_granularity == "monthly":
+        df["year"] = df[timestamp_col].dt.year
+        df["month"] = df[timestamp_col].dt.month
+
+        if count_col:
+            df_prepared = (
+                df.groupby(["year", "month", entity_col])[count_col]
+                .sum()
+                .reset_index(name="count")
+                .sort_values(["year", "month", entity_col])
+            )
+        else:
+            df_prepared = (
+                df.groupby(["year", "month", entity_col])
+                .size()
+                .reset_index(name="count")
+                .sort_values(["year", "month", entity_col])
+            )
+
     else:  # yearly
         df["year"] = df[timestamp_col].dt.year
 
@@ -267,6 +286,16 @@ def fit_priority_matrix(
         mean_time = df_prepared["time_continuous"].mean()
         df_prepared["time"] = df_prepared["time_continuous"] - mean_time
 
+    elif temporal_granularity == "monthly":
+        # continuous monthly time: year + (month-1)/12
+        df_prepared["time_continuous"] = (
+            df_prepared["year"] + (df_prepared["month"] - 1) / 12
+        )
+
+        # center for numerical stability
+        mean_time = df_prepared["time_continuous"].mean()
+        df_prepared["time"] = df_prepared["time_continuous"] - mean_time
+
     else:  # yearly
         # center year for numerical stability
         mean_year = df_prepared["year"].mean()
@@ -280,6 +309,8 @@ def fit_priority_matrix(
         df_prepared["quarter"] = df_prepared["quarter"].astype("category")
     elif temporal_granularity == "semiannual":
         df_prepared["semester"] = df_prepared["semester"].astype("category")
+    elif temporal_granularity == "monthly":
+        df_prepared["month"] = df_prepared["month"].astype("category")
 
     # ensure positive counts for poisson
     df_prepared = df_prepared[df_prepared["count"] > 0]
@@ -296,10 +327,14 @@ def fit_priority_matrix(
         formula += " + C(quarter)"
     elif temporal_granularity == "semiannual" and n_years >= 2:
         formula += " + C(semester)"
+    elif temporal_granularity == "monthly" and n_years >= 2:
+        formula += " + C(month)"
     elif temporal_granularity == "quarterly" and n_years == 1:
         print("  Warning: Single-year quarterly data detected, skipping seasonal dummies to avoid multicollinearity")
     elif temporal_granularity == "semiannual" and n_years == 1:
         print("  Warning: Single-year semiannual data detected, skipping seasonal dummies to avoid multicollinearity")
+    elif temporal_granularity == "monthly" and n_years == 1:
+        print("  Warning: Single-year monthly data detected, skipping seasonal dummies to avoid multicollinearity")
 
     # random effects: intercept + slope per entity
     random_formulas = {

{priorityx-0.2.5 → priorityx-0.2.6}/src/priorityx/tracking/movement.py

@@ -44,11 +44,32 @@ def _quarter_label(ts: pd.Timestamp) -> str:
     return f"{ts.year}-Q{quarter}"
 
 
+def _is_month_start(ts: pd.Timestamp) -> bool:
+    """Check if timestamp is the first day of a calendar month."""
+
+    return ts.day == 1
+
+
+def _next_month_start(ts: pd.Timestamp) -> pd.Timestamp:
+    """Get timestamp for the first day of the next calendar month."""
+
+    year = ts.year
+    month = ts.month
+    if month == 12:
+        return pd.Timestamp(year=year + 1, month=1, day=1)
+    return pd.Timestamp(year=year, month=month + 1, day=1)
+
+
+def _month_label(ts: pd.Timestamp) -> str:
+    """Format timestamp into 'YYYY-MM' label."""
+
+    return ts.strftime("%Y-%m")
+
+
 def _build_quarter_schedule_from_range(
     start_date: str, end_date: str
 ) -> list[tuple[str, str]]:
-    """
-    Build quarter schedule from date range.
+    """Build quarter schedule from date range.
 
     Args:
         start_date: Start date (YYYY-MM-DD), must be quarter boundary
@@ -85,6 +106,44 @@ def _build_quarter_schedule_from_range(
     return schedule
 
 
+def _build_month_schedule_from_range(
+    start_date: str, end_date: str
+) -> list[tuple[str, str]]:
+    """Build month schedule from date range.
+
+    Args:
+        start_date: Start date (YYYY-MM-DD), must be month boundary (day=1)
+        end_date: End date (YYYY-MM-DD), must be month boundary (day=1)
+
+    Returns:
+        List of (label, exclusive_end_date) tuples
+
+    Raises:
+        ValueError: If dates are not month boundaries or invalid
+    """
+
+    start_ts = pd.Timestamp(start_date)
+    end_ts = pd.Timestamp(end_date)
+
+    if start_ts >= end_ts:
+        raise ValueError("Start date must be earlier than end date")
+
+    if not _is_month_start(start_ts) or not _is_month_start(end_ts):
+        raise ValueError("Dates must be month boundaries (YYYY-MM-01)")
+
+    schedule: list[tuple[str, str]] = []
+    current = start_ts
+    while current < end_ts:
+        next_start = _next_month_start(current)
+        if next_start > end_ts:
+            next_start = end_ts
+
+        schedule.append((_month_label(current), next_start.strftime("%Y-%m-%d")))
+        current = next_start
+
+    return schedule
+
+
 def _build_default_quarter_schedule(
     df: pd.DataFrame, timestamp_col: str
 ) -> list[tuple[str, str]]:
@@ -120,67 +179,116 @@ def _build_default_quarter_schedule(
     )
 
 
-def normalize_quarter_schedule(
+def _build_default_month_schedule(
+    df: pd.DataFrame, timestamp_col: str
+) -> list[tuple[str, str]]:
+    """Create default month schedule spanning the dataset."""
+
+    if timestamp_col not in df.columns or len(df) == 0:
+        return []
+
+    df = df.copy()
+    df[timestamp_col] = pd.to_datetime(df[timestamp_col])
+
+    min_date = df[timestamp_col].min()
+    max_date = df[timestamp_col].max()
+
+    if pd.isna(min_date) or pd.isna(max_date):
+        return []
+
+    start_ts = min_date.to_period("M").to_timestamp(how="start")
+    max_month_start = max_date.to_period("M").to_timestamp(how="start")
+    end_ts = _next_month_start(max_month_start)
+
+    return _build_month_schedule_from_range(
+        start_ts.strftime("%Y-%m-%d"), end_ts.strftime("%Y-%m-%d")
+    )
+
+
+def normalize_period_schedule(
     quarters: Optional[Sequence[Union[tuple[str, str], str]]],
     df: pd.DataFrame,
     timestamp_col: str,
+    temporal_granularity: str = "quarterly",
 ) -> list[tuple[str, str]]:
-    """
-    Normalize quarter schedule to standard format.
+    """Normalize period schedule to standard (label, cutoff_date) format.
 
-    Accepts three input formats:
+    For quarterly granularity:
     1. Explicit schedule: [("2024-Q2", "2024-07-01"), ...]
-    2. Date range: ["2024-01-01", "2025-10-01"] (auto-generates quarters)
+    2. Date range: ["2024-01-01", "2025-10-01"]
     3. None: Auto-detect from data
 
-    Args:
-        quarters: Quarter specification (see formats above)
-        df: Input pandas DataFrame
-        timestamp_col: Column name for timestamp
+    For monthly granularity, the same patterns apply but labels are
+    "YYYY-MM" and dates must be month boundaries.
+    """
 
-    Returns:
-        List of (quarter_label, exclusive_end_date) tuples
+    if temporal_granularity == "monthly":
+        if quarters is None:
+            return _build_default_month_schedule(df, timestamp_col)
 
-    Examples:
-        >>> # explicit schedule
-        >>> normalize_quarter_schedule(
-        ...     [("2024-Q1", "2024-04-01"), ("2024-Q2", "2024-07-01")],
-        ...     df, "date"
-        ... )
+        if len(quarters) == 0:
+            return []
 
-        >>> # date range (auto-generates quarters)
-        >>> normalize_quarter_schedule(
-        ...     ["2024-01-01", "2025-01-01"], df, "date"
-        ... )
+        # date range format: ["2024-01-01", "2025-10-01"]
+        if len(quarters) == 2 and all(isinstance(q, str) for q in quarters):
+            return _build_month_schedule_from_range(quarters[0], quarters[1])
 
-        >>> # auto-detect from data
-        >>> normalize_quarter_schedule(None, df, "date")
-    """
+        normalized_schedule: list[tuple[str, str]] = []
+        for entry in quarters:
+            if not isinstance(entry, tuple) or len(entry) != 2:
+                raise ValueError(
+                    "quarters must be a list of (label, cutoff_date) tuples "
+                    "or two date boundary strings",
+                )
+            label, cutoff = entry
+            normalized_schedule.append((label, cutoff))
+
+        return normalized_schedule
+
+    # default: quarterly schedule
     if quarters is None:
         return _build_default_quarter_schedule(df, timestamp_col)
 
     if len(quarters) == 0:
         return []
 
-    # check first element type
-    quarters[0]
-
     # date range format: ["2024-01-01", "2025-10-01"]
     if len(quarters) == 2 and all(isinstance(q, str) for q in quarters):
         return _build_quarter_schedule_from_range(quarters[0], quarters[1])
 
     # explicit schedule format: [("2024-Q2", "2024-07-01"), ...]
-    normalized_schedule: list[tuple[str, str]] = []
+    normalized_schedule2: list[tuple[str, str]] = []
     for entry in quarters:
         if not isinstance(entry, tuple) or len(entry) != 2:
             raise ValueError(
                 "quarters must be a list of (label, cutoff_date) tuples "
-                "or two quarter boundary strings"
+                "or two quarter boundary strings",
             )
         label, cutoff = entry
-        normalized_schedule.append((label, cutoff))
+        normalized_schedule2.append((label, cutoff))
+
+    return normalized_schedule2
 
-    return normalized_schedule
+
+def normalize_quarter_schedule(
+    quarters: Optional[Sequence[Union[tuple[str, str], str]]],
+    df: pd.DataFrame,
+    timestamp_col: str,
+    temporal_granularity: str = "quarterly",
+) -> list[tuple[str, str]]:
+    """Backward-compatible alias for :func:`normalize_period_schedule`.
+
+    Historically this helper only handled quarterly schedules; it now
+    delegates to ``normalize_period_schedule`` which supports both
+    quarterly and monthly granularities.
+    """
+
+    return normalize_period_schedule(
+        quarters,
+        df,
+        timestamp_col,
+        temporal_granularity=temporal_granularity,
+    )
 
 
 def track_cumulative_movement(
@@ -208,7 +316,7 @@ def track_cumulative_movement(
         df: Input pandas DataFrame
         entity_col: Column name for entity identifier
         timestamp_col: Column name for timestamp (datetime type)
-        quarters: Quarter specification (see normalize_quarter_schedule)
+        quarters: Period specification (see normalize_period_schedule)
         min_total_count: Minimum total count for inclusion (default: 20)
         decline_window_quarters: Max quarters after last observation (default: 6)
         temporal_granularity: Time granularity for GLMM ('quarterly', 'yearly', 'semiannual')
@@ -217,10 +325,12 @@ def track_cumulative_movement(
 
     Returns:
         Tuple of (movement_df, metadata_dict)
-        - movement_df: Quarter-by-quarter tracking with columns:
+        - movement_df: Period-by-period tracking with columns:
           [entity, quarter, period_count, cumulative_count, period_x, period_y,
            period_quadrant, global_quadrant, global_x, global_y,
            count_total, x_delta, y_delta, quadrant_differs]
+          (the ``quarter`` column serves as the canonical period axis
+          for both quarterly and monthly granularities)
         - metadata_dict: Tracking statistics and configuration
 
     Examples:
@@ -239,15 +349,22 @@ def track_cumulative_movement(
     df = df.copy()
     df[timestamp_col] = pd.to_datetime(df[timestamp_col])
 
-    # normalize quarter schedule
-    quarter_schedule = normalize_quarter_schedule(quarters, df, timestamp_col)
+    # normalize quarter/month schedule (generic period schedule)
+    period_schedule = normalize_period_schedule(
+        quarters,
+        df,
+        timestamp_col,
+        temporal_granularity=temporal_granularity,
+    )
+
+    period_col = "quarter"
 
-    if len(quarter_schedule) == 0:
-        print("Warning: No quarter boundaries available for cumulative tracking")
+    if len(period_schedule) == 0:
+        print("Warning: No period boundaries available for cumulative tracking")
         empty_df = pd.DataFrame(
             columns=[
                 "entity",
-                "quarter",
+                period_col,
                 "period_count",
                 "cumulative_count",
                 "period_x",
@@ -308,8 +425,8 @@ def track_cumulative_movement(
     # step 2: determine valid entities at analysis endpoint
     print("\n[2/3] Determining valid entities at analysis endpoint...")
 
-    # get endpoint (last quarter)
-    final_quarter_name, final_quarter_date = quarter_schedule[-1]
+    # get endpoint (last period in schedule)
+    final_quarter_name, final_quarter_date = period_schedule[-1]
     print(f"Analysis endpoint: {final_quarter_name} ({final_quarter_date})")
 
     # calculate valid entities based on cumulative totals up to endpoint
@@ -360,12 +477,12 @@ def track_cumulative_movement(
         f"{n_valid_at_endpoint}"
     )
 
-    # step 3: track movement through quarters
-    print(f"\n[3/3] Tracking movement through {len(quarter_schedule)} quarters...")
+    # step 3: track movement through periods
+    print(f"\n[3/3] Tracking movement through {len(period_schedule)} periods...")
 
     movement_records = []
 
-    for quarter_name, end_date_str in quarter_schedule:
+    for quarter_name, end_date_str in period_schedule:
         print(f"  [{quarter_name}] Running GLMM on cumulative data...", end=" ")
 
         # filter to cumulative data up to this quarter
@@ -402,7 +519,7 @@ def track_cumulative_movement(
                     movement_records.append(
                         {
                             "entity": entity,
-                            "quarter": quarter_name,
+                            period_col: quarter_name,
                             "cumulative_count": row["count"],
                             "period_x": row["Random_Intercept"],
                             "period_y": row["Random_Slope"],
@@ -426,7 +543,7 @@ def track_cumulative_movement(
         movement_df = pd.DataFrame(
             columns=[
                 "entity",
-                "quarter",
+                period_col,
                 "period_count",
                 "cumulative_count",
                 "period_x",
@@ -445,8 +562,8 @@ def track_cumulative_movement(
     # step 4: calculate movement metrics
     print("\n[4/4] Calculating movement metrics...")
 
-    # add quarter-over-quarter changes
-    movement_df = movement_df.sort_values(["entity", "quarter"])
+    # add period-over-period changes
+    movement_df = movement_df.sort_values(["entity", period_col])
 
     # calculate deltas
     movement_df["x_delta"] = movement_df.groupby("entity")["period_x"].diff()
@@ -465,7 +582,7 @@ def track_cumulative_movement(
     # reorder columns for readability
     cols = [
         "entity",
-        "quarter",
+        period_col,
         "period_count",
         "cumulative_count",
         "period_x",
@@ -485,9 +602,9 @@ def track_cumulative_movement(
         + [c for c in movement_df.columns if c not in cols]
     ]
 
-    print(f"Tracked {len(movement_df)} entity-quarter observations")
+    print(f"Tracked {len(movement_df)} entity-period observations")
     print(f"Entities tracked: {movement_df['entity'].nunique()}")
-    print(f"Periods covered: {movement_df['quarter'].nunique()}")
+    print(f"Periods covered: {movement_df[period_col].nunique()}")
 
     divergence_count = movement_df["quadrant_differs"].sum()
     divergence_pct = (
@@ -500,11 +617,11 @@ def track_cumulative_movement(
         "entities_tracked": movement_df["entity"].nunique()
         if not movement_df.empty
         else 0,
-        "quarters_analyzed": len(quarter_schedule),
+        "quarters_analyzed": len(period_schedule),
         "total_observations": len(movement_df),
         "divergence_rate": divergence_pct,
         "temporal_granularity": temporal_granularity,
-        "quarter_schedule": quarter_schedule,
+        "quarter_schedule": period_schedule,
     }
 
     return movement_df, metadata
@@ -531,9 +648,36 @@ def load_or_track_movement(
 
     csv_path: str | None = None
     if use_cache:
-        csv_path = latest_artifact_csv("movement", entity_name, output_dir)
+        csv_path = latest_artifact_csv(
+            "movement",
+            entity_name,
+            output_dir,
+            temporal_granularity=temporal_granularity,
+        )
         if csv_path:
             movement_df = pd.read_csv(csv_path)
+            if temporal_granularity == "monthly":
+                # New-style monthly CSVs use a friendlier ``month``
+                # column on disk; normalize to ``quarter`` in-memory
+                # for compatibility with existing code.
+                if (
+                    "month" in movement_df.columns
+                    and "quarter" not in movement_df.columns
+                ):
+                    movement_df = movement_df.rename(columns={"month": "quarter"})
+
+                # Legacy monthly CSVs were written with a ``quarter``
+                # column. Treat that as ``month`` for users by
+                # rewriting the CSV header to ``month`` while keeping
+                # the in-memory schema unchanged.
+                elif (
+                    "quarter" in movement_df.columns
+                    and "month" not in movement_df.columns
+                ):
+                    month_df = movement_df.rename(columns={"quarter": "month"})
+                    month_df.to_csv(csv_path, index=False)
+                    movement_df = month_df.rename(columns={"month": "quarter"})
+
             return movement_df, csv_path
 
     movement_df, _meta = track_cumulative_movement(
@@ -545,8 +689,14 @@ def load_or_track_movement(
         temporal_granularity=temporal_granularity,
     )
 
+    # For monthly outputs, persist a friendlier "month" label on disk
+    # while keeping the in-memory DataFrame schema unchanged.
+    movement_to_save = movement_df
+    if temporal_granularity == "monthly" and "quarter" in movement_df.columns:
+        movement_to_save = movement_df.rename(columns={"quarter": "month"})
+
     csv_path = save_dataframe_to_csv(
-        movement_df,
+        movement_to_save,
         artifact="movement",
         entity_name=entity_name,
         temporal_granularity=temporal_granularity,

{priorityx-0.2.5 → priorityx-0.2.6}/src/priorityx/utils/helpers.py

@@ -260,6 +260,7 @@ def generate_output_path(
         "quarterly": "Q",
         "yearly": "Y",
         "semiannual": "S",
+        "monthly": "M",
     }.get(temporal_granularity, "Q")
 
     timestamp = datetime.now().strftime("%Y%m%d")
@@ -305,15 +306,31 @@ def latest_artifact_csv(
     artifact: str,
     entity_name: str,
     output_dir: str = "results/csv",
+    temporal_granularity: str | None = None,
 ) -> str | None:
     """Find the latest CSV for a given artifact/entity pair.
 
     Assumes filenames follow ``generate_output_path`` convention:
     ``<output_dir>/<artifact>-<entity_slug>-<granularity>-<YYYYMMDD>.csv``.
+
+    If ``temporal_granularity`` is provided, restricts matches to that
+    granularity suffix (e.g. "Q", "M"); otherwise returns the latest
+    CSV across all granularities.
     """
 
     slug = entity_name.lower().replace(" ", "_")
     directory = Path(output_dir)
-    pattern = f"{artifact}-{slug}-*.csv"
+
+    if temporal_granularity is not None:
+        granularity_suffix = {
+            "quarterly": "Q",
+            "yearly": "Y",
+            "semiannual": "S",
+            "monthly": "M",
+        }.get(temporal_granularity, "Q")
+        pattern = f"{artifact}-{slug}-{granularity_suffix}-*.csv"
+    else:
+        pattern = f"{artifact}-{slug}-*.csv"
+
     matches = sorted(directory.glob(pattern))
     return str(matches[-1]) if matches else None

{priorityx-0.2.5 → priorityx-0.2.6}/src/priorityx/viz/matrix.py

@@ -8,6 +8,8 @@ import matplotlib.ticker as ticker
 import pandas as pd
 from matplotlib.lines import Line2D
 
+from priorityx.core.quadrants import get_quadrant_label
+
 # try to import adjustText for label positioning
 try:
     from adjustText import adjust_text
@@ -65,7 +67,7 @@ def plot_priority_matrix(
         save_csv: Save data to CSV
         plot_dir: Output directory for plot files
         csv_dir: Output directory for CSV files
-        temporal_granularity: Time granularity ('quarterly', 'yearly', 'semiannual')
+        temporal_granularity: Time granularity ('quarterly', 'yearly', 'semiannual', 'monthly')
         close_fig: Close the figure before returning (set True if you see duplicate inline renders)
 
     Returns:
@@ -144,16 +146,14 @@ def plot_priority_matrix(
 
     # define colors for each quadrant (tab20 - distinct hues)
     colors = {
-        "Q1": "#d62728",  # tab red - critical
-        "Q2": "#ff7f0e",  # tab orange - investigate
-        "Q4": "#1f77b4",  # tab blue - low priority
-        "Q3": "#2ca02c",  # tab green - monitor
+        "Q1": "#d62728",  # top-right quadrant
+        "Q2": "#ff7f0e",  # top-left quadrant
+        "Q4": "#1f77b4",  # bottom-right quadrant
+        "Q3": "#2ca02c",  # bottom-left quadrant
     }
     quadrant_display = {
-        "Q1": "Q1 (Critical)",
-        "Q2": "Q2 (Investigate)",
-        "Q3": "Q3 (Monitor)",
-        "Q4": "Q4 (Low Priority)",
+        q: get_quadrant_label(q, x_label="Volume", y_label="Growth")
+        for q in ["Q1", "Q2", "Q3", "Q4"]
     }
 
     # plot all points
@@ -316,6 +316,7 @@ def plot_priority_matrix(
             "quarterly": "Q",
             "yearly": "Y",
             "semiannual": "S",
+            "monthly": "M",
         }.get(temporal_granularity, "Q")
         save_path = f"{plot_dir}/priority_matrix-{entity_name.lower()}-{granularity_suffix}-{timestamp}.png"
 
@@ -333,6 +334,7 @@ def plot_priority_matrix(
             "quarterly": "Q",
             "yearly": "Y",
             "semiannual": "S",
+            "monthly": "M",
         }.get(temporal_granularity, "Q")
         csv_path = f"{csv_dir}/priority_matrix-{entity_name.lower()}-{granularity_suffix}-{timestamp}.csv"
 

{priorityx-0.2.5 → priorityx-0.2.6}/src/priorityx/viz/timeline.py

@@ -24,7 +24,7 @@ def plot_transition_timeline(
     max_entities: Optional[int] = 20,
     figsize: Tuple[int, int] = (16, 12),
     title: Optional[str] = None,
-    x_axis_granularity: Literal["quarterly", "semiannual", "yearly"] = "quarterly",
+    x_axis_granularity: Literal["quarterly", "semiannual", "yearly", "monthly"] = "quarterly",
     sort_by_risk_first: bool = True,
     entity_name: str = "Entity",
     show_all_periods: bool = False,
@@ -106,7 +106,7 @@ def plot_transition_timeline(
     risk_order = {"critical": 0, "high": 1, "medium": 2, "low": 3}
     df["risk_order"] = df["risk_level"].map(risk_order)
 
-    # aggregate quarters based on granularity
+    # aggregate periods based on granularity
     if x_axis_granularity == "semiannual":
 
         def quarter_to_semester(q_str):
@@ -125,6 +125,9 @@ def plot_transition_timeline(
             return q_str
 
         df["period"] = df["transition_quarter"].apply(quarter_to_year)
+    elif x_axis_granularity == "monthly":
+        # use transition_quarter as-is (assumed monthly label like YYYY-MM)
+        df["period"] = df["transition_quarter"]
     else:  # quarterly
         df["period"] = df["transition_quarter"]
 
@@ -267,9 +270,14 @@ def plot_transition_timeline(
         ax.scatter(x_pos, y_pos, s=100, c=color, alpha=0.8, zorder=2)
 
         # add transition label with spike indicator
-        label = f"{transition['from_quadrant']}→{transition['to_quadrant']}"
+        to_quad = str(transition["to_quadrant"])
+        label = f"{transition['from_quadrant']}→{to_quad}"
+
+        # avoid duplicating spike markers when to_quadrant already
+        # contains *X / *Y / *XY
+        has_inline_spike = "*" in to_quad
 
-        if spike_axis:
+        if spike_axis and not has_inline_spike:
             # add superscript indicator
             if spike_axis == "Y":
                 label += "*$^Y$"
@@ -313,7 +321,9 @@ def plot_transition_timeline(
                 period_labels.append(f"H{semester} {year}")
             else:
                 period_labels.append(p)
-    else:  # yearly
+    elif x_axis_granularity == "yearly":
+        period_labels = periods
+    else:  # monthly
         period_labels = periods
 
     ax.set_xticks(range(len(periods)))
@@ -365,7 +375,12 @@ def plot_transition_timeline(
         )
 
     # set labels
-    xlabel_map = {"quarterly": "Quarter", "semiannual": "Semester", "yearly": "Year"}
+    xlabel_map = {
+        "quarterly": "Quarter",
+        "semiannual": "Semester",
+        "yearly": "Year",
+        "monthly": "Month",
+    }
     axis_fontsize = 15
     ax.set_xlabel(xlabel_map.get(x_axis_granularity, "Period"), fontsize=axis_fontsize)
     ax.set_ylabel(entity_name, fontsize=axis_fontsize)
@@ -389,6 +404,7 @@ def plot_transition_timeline(
             "quarterly": "Q",
             "yearly": "Y",
             "semiannual": "S",
+            "monthly": "M",
         }.get(temporal_granularity, "Q")
         plot_path = f"{plot_dir}/transition_timeline-{entity_name.lower()}-{granularity_suffix}-{timestamp}.png"
         plt.savefig(plot_path, dpi=300, bbox_inches="tight", format="png")
@@ -405,9 +421,20 @@ def plot_transition_timeline(
             "quarterly": "Q",
             "yearly": "Y",
             "semiannual": "S",
+            "monthly": "M",
         }.get(temporal_granularity, "Q")
         csv_path = f"{csv_dir}/transitions-{entity_name.lower()}-{granularity_suffix}-{timestamp}.csv"
-        df.to_csv(csv_path, index=False)
+
+        df_to_save = df
+        # For monthly outputs, expose a clearer ``transition_month`` label
+        # in the CSV while keeping the internal transition_quarter column
+        # for code that relies on it.
+        if temporal_granularity == "monthly" and "transition_quarter" in df.columns:
+            df_to_save = df.copy().rename(
+                columns={"transition_quarter": "transition_month"}
+            )
+
+        df_to_save.to_csv(csv_path, index=False)
         print(f"Transitions CSV saved: {csv_path}")
 
     if close_fig:

{priorityx-0.2.5 → priorityx-0.2.6}/src/priorityx/viz/trajectory.py

@@ -6,6 +6,7 @@ import warnings
 import matplotlib.pyplot as plt
 import pandas as pd
 
+from priorityx.core.quadrants import get_quadrant_label
 from priorityx.utils.helpers import save_dataframe_to_csv
 
 # suppress noisy FancyArrowPatch fallback warnings from annotate/adjustments
@@ -120,16 +121,14 @@ def plot_entity_trajectories(
 
     # define colors for quadrants (tab20 - distinct hues)
     colors = {
-        "Q1": "#d62728",  # critical
-        "Q2": "#ff7f0e",  # investigate
-        "Q4": "#1f77b4",  # low priority
-        "Q3": "#2ca02c",  # monitor
+        "Q1": "#d62728",  # top-right quadrant
+        "Q2": "#ff7f0e",  # top-left quadrant
+        "Q4": "#1f77b4",  # bottom-right quadrant
+        "Q3": "#2ca02c",  # bottom-left quadrant
     }
     quadrant_display = {
-        "Q1": "Q1 (Critical)",
-        "Q2": "Q2 (Investigate)",
-        "Q3": "Q3 (Monitor)",
-        "Q4": "Q4 (Low Priority)",
+        q: get_quadrant_label(q, x_label="Volume", y_label="Growth")
+        for q in ["Q1", "Q2", "Q3", "Q4"]
     }
 
     # track usage counts per color to slightly vary hue if needed
@@ -308,15 +307,19 @@ def plot_entity_trajectories(
             "quarterly": "Q",
             "yearly": "Y",
             "semiannual": "S",
+            "monthly": "M",
         }.get(temporal_granularity, "Q")
         plot_path = f"{plot_dir}/trajectories-{entity_name.lower()}-{granularity_suffix}-{timestamp}.png"
         plt.savefig(plot_path, dpi=300, bbox_inches="tight", format="png")
         print(f"Entity trajectory plot saved: {plot_path}")
 
     if save_csv:
+        # Only save the trajectories actually plotted (df_plot), not the
+        # full movement_df. The full movement data remains available in
+        # the movement CSVs.
         target_dir = csv_dir if csv_dir else f"{plot_dir}/../results"
         csv_path = save_dataframe_to_csv(
-            movement_df,
+            df_plot,
             artifact="trajectories",
             entity_name=entity_name,
             temporal_granularity=temporal_granularity,

{priorityx-0.2.5 → priorityx-0.2.6}/tests/test_glmm.py

@@ -67,6 +67,23 @@ def test_fit_priority_matrix_stats():
     assert stats["temporal_granularity"] == "quarterly"
 
 
+def test_fit_priority_matrix_monthly_basic():
+    """Monthly granularity should run and report correct stats flag."""
+
+    df = generate_test_data()
+
+    results, stats = fit_priority_matrix(
+        df,
+        entity_col="entity",
+        timestamp_col="date",
+        temporal_granularity="monthly",
+        min_observations=3,
+    )
+
+    assert len(results) > 0
+    assert stats["temporal_granularity"] == "monthly"
+
+
 def test_fit_priority_matrix_seed_control():
     """Verify explicit seeding produces deterministic random effects."""
 

{priorityx-0.2.5 → priorityx-0.2.6}/uv.lock

@@ -2270,7 +2270,7 @@ wheels = [
 
 [[package]]
 name = "priorityx"
-version = "0.2.3"
+version = "0.2.5"
 source = { editable = "." }
 dependencies = [
     { name = "adjusttext" },

{priorityx-0.2.5 → priorityx-0.2.6}/examples/incidents/incident_monitoring.py

@@ -3,8 +3,6 @@
 
 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
@@ -21,6 +19,8 @@ from priorityx.utils.helpers import (
     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")