feat: average administered doses chart tab (Task D.2)

src/data_processing/pathway_queries.py

@@ -1443,6 +1443,93 @@ def get_drug_timeline(
         conn.close()
 
 
+def get_dosing_distribution(
+    db_path: Path,
+    date_filter_id: str,
+    chart_type: str,
+    directory: Optional[str] = None,
+    trust: Optional[str] = None,
+) -> list[dict]:
+    """Level 3 drug nodes with average administered dose counts.
+
+    Parses the average_administered JSON array (position 0 = avg doses for the drug).
+    Aggregates across trusts using weighted averages by patient count.
+
+    Returns list of dicts sorted by avg_doses desc:
+        [{drug, directory, avg_doses, patients}]
+    """
+    import json
+
+    conn = sqlite3.connect(str(db_path))
+    conn.row_factory = sqlite3.Row
+    try:
+        where = ["date_filter_id = ?", "chart_type = ?", "level = 3",
+                 "average_administered IS NOT NULL", "average_administered != ''"]
+        params: list = [date_filter_id, chart_type]
+
+        if directory:
+            where.append("directory = ?")
+            params.append(directory)
+        if trust:
+            where.append("trust_name = ?")
+            params.append(trust)
+
+        query = f"""
+            SELECT labels AS drug, directory, trust_name,
+                   value AS patients, average_administered
+            FROM pathway_nodes
+            WHERE {' AND '.join(where)}
+            ORDER BY labels, directory
+        """
+        rows = conn.execute(query, params).fetchall()
+
+        # Aggregate across trusts: weighted average of dose count
+        agg = {}
+        for r in rows:
+            patients = r["patients"] or 0
+            if patients == 0:
+                continue
+
+            try:
+                arr = json.loads(r["average_administered"].replace("NaN", "null"))
+            except (json.JSONDecodeError, AttributeError):
+                continue
+
+            # Position 0 is average doses for this drug
+            avg_doses = arr[0] if arr and arr[0] is not None else None
+            if avg_doses is None or avg_doses <= 0:
+                continue
+
+            key = (r["directory"] or "", r["drug"])
+            if key not in agg:
+                agg[key] = {
+                    "drug": r["drug"],
+                    "directory": r["directory"] or "",
+                    "weighted_doses": 0.0,
+                    "total_patients": 0,
+                }
+            agg[key]["weighted_doses"] += avg_doses * patients
+            agg[key]["total_patients"] += patients
+
+        result = []
+        for v in agg.values():
+            tp = v["total_patients"]
+            if tp > 0:
+                result.append({
+                    "drug": v["drug"],
+                    "directory": v["directory"],
+                    "avg_doses": round(v["weighted_doses"] / tp, 1),
+                    "patients": tp,
+                })
+
+        result.sort(key=lambda x: -x["avg_doses"])
+        return result
+    except sqlite3.Error:
+        return []
+    finally:
+        conn.close()
+
+
 def get_directorate_summary(
     db_path: Path,
     date_filter_id: str,

src/visualization/plotly_generator.py

@@ -2206,3 +2206,94 @@ def create_drug_timeline_figure(data: list[dict], title: str = "") -> go.Figure:
     fig.update_layout(**layout)
 
     return fig
+
+
+def create_dosing_distribution_figure(
+    data: list[dict], title: str = ""
+) -> go.Figure:
+    """Create horizontal bar chart of average administered doses per drug.
+
+    Args:
+        data: list of dicts with keys: drug, directory, avg_doses, patients
+        title: chart title suffix
+    """
+    if not data:
+        return go.Figure()
+
+    display_title = f"Average Administered Doses — {title}" if title else "Average Administered Doses"
+
+    # Group by directory for coloring
+    directories = sorted(set(d["directory"] for d in data))
+    dir_colors = {
+        d: DRUG_PALETTE[i % len(DRUG_PALETTE)]
+        for i, d in enumerate(directories)
+    }
+
+    single_directory = len(directories) == 1
+
+    # Sort by avg_doses descending
+    sorted_data = sorted(data, key=lambda x: x["avg_doses"])
+
+    # Build y-labels
+    if single_directory:
+        y_labels = [d["drug"] for d in sorted_data]
+    else:
+        y_labels = [f"{d['drug']} ({d['directory']})" for d in sorted_data]
+
+    fig = go.Figure()
+
+    # One trace per directory for legend grouping
+    shown_dirs = set()
+    for i, row in enumerate(sorted_data):
+        d = row["directory"]
+        show_legend = d not in shown_dirs
+        shown_dirs.add(d)
+
+        fig.add_trace(go.Bar(
+            y=[y_labels[i]],
+            x=[row["avg_doses"]],
+            orientation="h",
+            marker_color=dir_colors[d],
+            name=d,
+            showlegend=show_legend,
+            legendgroup=d,
+            text=[f"{row['avg_doses']:.0f}"],
+            textposition="inside",
+            textfont=dict(color="white", size=11),
+            hovertemplate=(
+                f"<b>{row['drug']}</b><br>"
+                f"Directory: {d}<br>"
+                f"Avg doses: {row['avg_doses']:.1f}<br>"
+                f"Patients: {row['patients']:,}"
+                "<extra></extra>"
+            ),
+        ))
+
+    n_bars = len(sorted_data)
+    bar_height = 24
+    dynamic_height = max(400, n_bars * bar_height + 120)
+
+    n_dirs = len(directories)
+    legend_margins = _smart_legend_margin(n_dirs)
+    legend = _smart_legend(n_dirs, legend_title="Directory")
+
+    layout = _base_layout(display_title)
+    layout.update(
+        xaxis=dict(
+            title="Average Doses Administered",
+            gridcolor=GRID_COLOR,
+            zeroline=False,
+        ),
+        yaxis=dict(
+            automargin=True,
+            tickfont=dict(size=11),
+        ),
+        barmode="overlay",
+        height=dynamic_height,
+        margin=dict(t=60, l=8, **legend_margins),
+        legend=legend,
+        bargap=0.3,
+    )
+    fig.update_layout(**layout)
+
+    return fig