[FIX/FEAT] Move bottleneck analysis from tab4 to tab5, add chart interpretation captions to both tabs

tabs/tab4_optimization.py

@@ -827,6 +827,12 @@ def show_resource_balance(latest):
         None
     """
     st.markdown('<p class="crra-sub-heading">Resource balance: used vs available</p>', unsafe_allow_html=True)
+    st.markdown(
+        '<p class="caption">Green bars show quantities consumed by the optimised portfolio; grey bars show the unused remainder. '
+        '<br>Resources with almost no grey bar are fully utilised and may be limiting further CDR. '
+        '<br>Resources with a large grey bar have spare capacity: either no method needs them or their demand is already saturated elsewhere.</p>',
+        unsafe_allow_html=True,
+    )
     resource_caps = latest["resource_caps"]
     used_total = latest["resource_used_total"]
 
@@ -884,45 +890,6 @@ def show_resource_balance(latest):
         st.dataframe(df, width='stretch', hide_index=True)
     register_chart_data("Resource balance (used vs remaining)", df)
 
-def show_bottleneck_analysis(latest):
-    """Render the resource sensitivity table (CDR gain per +1 unit of each resource).
-
-    Args:
-        latest (dict): result dict with keys resource_actual_gain, custom_resources.
-
-    Returns:
-        None
-    """
-    st.markdown('<p class="crra-sub-heading">Resource sensitivity</p>', unsafe_allow_html=True)
-    st.markdown(
-        '<p class="caption">'
-        'For every resource: actual CDR gain if you add exactly +1 unit, recomputed with all other constraints in place.'
-        '</p>',
-        unsafe_allow_html=True,
-    )
-
-    resource_to_group = get_resource_to_group()
-    custom_batch_lookup = {b["name"]: b for b in latest.get("custom_resources", [])}
-
-    actual_gains = latest.get("resource_actual_gain", {})
-    if actual_gains:
-        sp_rows = []
-        for r, gain in sorted(actual_gains.items(), key=lambda x: -x[1]):
-            if r in custom_batch_lookup:
-                unit = resource_unit_map.get(resource_to_group.get(custom_batch_lookup[r]["group"]), "?")
-            else:
-                unit = resource_unit_map.get(resource_to_group.get(r), "?")
-            sp_rows.append({
-                "Resource": r,
-                "Unit": unit,
-                f"CDR gain for +1 unit ({CO2_UNIT})": round(gain, 4),
-            })
-        df_sp = pd.DataFrame(sp_rows)
-        st.dataframe(df_sp, width='stretch', hide_index=True)
-        register_chart_data("Resource sensitivity (CDR gain per +1 unit)", df_sp)
-    else:
-        st.info("No resources to analyse.", icon=":material/info:")
-
 def save_scenario(latest):
     """Render the save-scenario widget and persist the current result to session state.
 
@@ -1378,11 +1345,10 @@ def render_tab():
     ]:
         st.session_state.setdefault(key, default)
 
-    tab_run, tab_results, tab_resources, tab_bottleneck, tab_export, tab_reset = st.tabs([
+    tab_run, tab_results, tab_resources, tab_export, tab_reset = st.tabs([
         "▶️ Run",
         "📊 Method allocation",
         "🌿 Resource usage",
-        "🔍 Bottleneck analysis",
         "💾 Export & Save",
         "🔄 Reset"
     ])
@@ -1419,7 +1385,7 @@ def render_tab():
 
     latest = st.session_state.get("latest_result")
     if not latest:
-        for tab in [tab_results, tab_resources, tab_bottleneck, tab_export]:
+        for tab in [tab_results, tab_resources, tab_export]:
             with tab:
                 st.markdown(no_results, unsafe_allow_html=True)
         with tab_reset:
@@ -1431,7 +1397,7 @@ def render_tab():
     method_costs = latest["method_costs"]
 
     if not allocations or sum(allocations.values()) == 0:
-        for tab in [tab_results, tab_resources, tab_bottleneck, tab_export]:
+        for tab in [tab_results, tab_resources, tab_export]:
             with tab:
                 st.markdown(no_results, unsafe_allow_html=True)
         with tab_reset:
@@ -1452,29 +1418,40 @@ def render_tab():
         st.markdown('<p class="crra-sub-heading">Optimization Summary</p>', unsafe_allow_html=True)
         st.dataframe(df_display, width='stretch')
         st.markdown('<p class="crra-sub-heading">Method allocation breakdown</p>', unsafe_allow_html=True)
+        st.markdown(
+            '<p class="caption">Share of total CO₂ removal contributed by each active method. '
+            'Larger slices indicate methods that dominate the portfolio.</p>',
+            unsafe_allow_html=True,
+        )
         show_donut(df_result)
 
     with tab_resources:
         st.markdown('<p class="crra-sub-heading">Resource usage heatmap (% of cap)</p>', unsafe_allow_html=True)
+        st.markdown(
+            '<p class="caption">Each cell shows what percentage of a resource\'s available cap is consumed by a given method.'
+            '<br>Dark cells indicate near-full use: those resource–method pairs are the most constrained.</p>',
+            unsafe_allow_html=True,
+        )
         show_heatmap(df_result, resource_caps, method_costs,
                      custom_resources=latest.get("custom_resources", []),
                      resource_usage=latest.get("resource_usage"))
         st.markdown('<p class="crra-sub-heading">Absolute resource usage by unit</p>', unsafe_allow_html=True)
+        st.markdown(
+            '<p class="caption">Absolute quantities consumed per resource and per method, in their native units. '
+            'Use this view to compare the scale of demand across resources with different units (e.g. ha, m³/yr, t/yr).</p>',
+            unsafe_allow_html=True,
+        )
         show_absolute_usage(allocations, method_costs,
                             custom_resources=latest.get("custom_resources", []),
                             resource_usage=latest.get("resource_usage"))
         show_resource_balance(latest)
 
-    with tab_bottleneck:
-        show_bottleneck_analysis(latest)
-
     with tab_export:
         render_export_tab(latest)
 
     with tab_reset:
         reset_scenario("reset")
 
-    st.markdown("---")
     if st.button("Sensitivity analysis →", key="btn-nav-next-optimization", type="primary", help="Explore how resource or method changes affect your portfolio."):
         st.session_state["_navigate_to"] = "Sensitivity analysis"
         st.rerun()

tabs/tab5_sensitivity.py

@@ -2,8 +2,8 @@ import copy
 import pandas as pd
 import streamlit as st
 import plotly.express as px
-from config.config import CO2_UNIT, hidden_resource_names, method_order, resource_order
-from utils.data_utils import (get_resource_to_unit, run_expanded_optimization,
+from config.config import CO2_UNIT, hidden_resource_names, method_order, resource_order, resource_unit_map
+from utils.data_utils import (get_resource_to_unit, get_resource_to_group, run_expanded_optimization,
                               is_other_method, get_other_method_variants, make_variant_name,
                               default_constraint)
 from utils.ui_helpers import register_chart_data, show_bar
@@ -65,6 +65,13 @@ def panel_resource_sensitivity(baseline_removed, all_resources, resource_to_unit
         '<p class="crra-sub-heading">Impact of resource availability</p>',
         unsafe_allow_html=True,
     )
+    st.markdown(
+        '<p class="caption">Each line shows how total CO₂ removal changes as one resource\'s availability varies from 0% to 200% of its current cap. '
+        '<br>The range goes up to 200% so you can see both the impact of a reduction and the potential gains from doubling availability. '
+        '<br>A steep curve means that resource strongly drives portfolio performance: small increases can yield large gains. '
+        '<br>A flat line means the portfolio is limited by something else (another resource or a method cap).</p>',
+        unsafe_allow_html=True,
+    )
     selected_resources = st.multiselect(
         "Select one or more resources:", all_resources, key="crra-select-resource"
     )
@@ -144,6 +151,14 @@ def panel_method_sensitivity(baseline_removed):
         '<p class="crra-sub-heading">Impact of max allocation per method</p>',
         unsafe_allow_html=True,
     )
+    st.markdown(
+        '<p class="caption">Each line shows how total CO₂ removal changes as one method\'s maximum deployment cap varies from 0% to 100% of its current setting: '
+        'whether that cap was defined as a percentage of potential or as an absolute value in the Method constraints tab. '
+        '<br>The scale stops at 100% because the cap represents a ceiling you set: going beyond it would mean overriding your own constraint. '
+        '<br>A steep curve means the cap is a binding constraint: relaxing it would allow more removal. '
+        '<br>A flat line means the method is already limited by resource availability, not by its cap.</p>',
+        unsafe_allow_html=True,
+    )
 
     # "Other"-tagged methods with custom batches attached are expanded into
     # independent variants (e.g. "Enhanced weathering - Other mineral: Ganite")
@@ -249,6 +264,54 @@ def panel_method_sensitivity(baseline_removed):
     register_chart_data("Sensitivity to method cap", df)
 
 
+def show_bottleneck_analysis():
+    """Render the resource sensitivity table (CDR gain per +1 unit of each resource).
+
+    Reads the latest optimization result from session state. Shows nothing if no
+    result is available yet.
+
+    Returns:
+        None
+    """
+    latest = st.session_state.get("latest_result")
+    if not latest:
+        st.info("Run the optimization first (Portfolio generation tab) to see the bottleneck analysis.", icon=":material/info:")
+        return
+
+    st.markdown('<p class="crra-sub-heading">Resource sensitivity</p>', unsafe_allow_html=True)
+    st.markdown(
+        '<p class="caption">'
+        'For each resource: the additional CO₂ that could be removed by adding exactly +1 unit, '
+        'recomputed with all other constraints held fixed. '
+        '<br>Resources at the top of the list are the most binding bottlenecks in your current portfolio: '
+        'prioritise increasing their availability to unlock the largest gains.'
+        '</p>',
+        unsafe_allow_html=True,
+    )
+
+    resource_to_group = get_resource_to_group()
+    custom_batch_lookup = {b["name"]: b for b in latest.get("custom_resources", [])}
+    actual_gains = latest.get("resource_actual_gain", {})
+
+    if actual_gains:
+        sp_rows = []
+        for r, gain in sorted(actual_gains.items(), key=lambda x: -x[1]):
+            if r in custom_batch_lookup:
+                unit = resource_unit_map.get(resource_to_group.get(custom_batch_lookup[r]["group"]), "?")
+            else:
+                unit = resource_unit_map.get(resource_to_group.get(r), "?")
+            sp_rows.append({
+                "Resource": r,
+                "Unit": unit,
+                f"CDR gain for +1 unit ({CO2_UNIT})": round(gain, 4),
+            })
+        df_sp = pd.DataFrame(sp_rows)
+        st.dataframe(df_sp, width='stretch', hide_index=True)
+        register_chart_data("Resource sensitivity (CDR gain per +1 unit)", df_sp)
+    else:
+        st.info("No resources to analyse.", icon=":material/info:")
+
+
 def render_tab():
     """Render the Sensitivity Analysis tab.
 
@@ -274,7 +337,7 @@ def render_tab():
 
     baseline_removed, all_resources, resource_to_unit = compute_baseline()
 
-    tab1, tab2 = st.tabs(["🔁 Resource sensitivity", "🔁 Method sensitivity"])
+    tab1, tab2, tab3 = st.tabs(["🔁 Resource sensitivity", "🔁 Method sensitivity", "🔍 Bottleneck analysis"])
 
     with tab1:
         panel_resource_sensitivity(baseline_removed, all_resources, resource_to_unit)
@@ -282,6 +345,9 @@ def render_tab():
     with tab2:
         panel_method_sensitivity(baseline_removed)
 
+    with tab3:
+        show_bottleneck_analysis()
+
     if st.button("Scenario comparison →", key="btn-nav-next-sensitivity", type="primary", help="Compare multiple saved scenarios side by side."):
         st.session_state["_navigate_to"] = "Scenario comparison"
         st.rerun()