[DOC] README: fix tab name, add tabs overview, custom resources, scenarios, Case 9, and missing data scripts

README.md

@@ -19,6 +19,9 @@ A Streamlit app for optimizing carbon removal portfolios across different method
 
 - [Data Maintenance Guide](#data-maintenance-guide)
   - [How it works](#how-it-works-overview)
+    - [App tabs](#app-tabs)
+    - [Custom resources](#custom-resources)
+    - [Scenarios (save and compare)](#scenarios-save-and-compare)
   - [Option 1: Hugging Face](#option-1-edit-directly-on-hugging-face-no-local-setup-needed)
   - [Option 2: Local](#option-2-work-locally)
   - [Quick reference](#quick-reference-where-is-each-parameter)
@@ -34,6 +37,7 @@ A Streamlit app for optimizing carbon removal portfolios across different method
   - [Case 6 - Change whether a resource is optional](#case-6--change-whether-a-resource-is-optional-secondary-for-a-method)
   - [Case 7 - Rename a method or resource](#case-7--rename-a-method-or-resource)
   - [Case 8 - Edit tooltip texts](#case-8--edit-tooltip-texts-hover-descriptions)
+  - [Case 9 - Remove a method or resource](#case-9--remove-a-method-or-resource)
   - [Case 10 - Change the display order](#case-10--change-the-display-order-of-methods-or-resources)
   - [After any change - checklist](#after-any-change--checklist)
 - [Library Maintenance Guide](#library-maintenance-guide)
@@ -66,7 +70,47 @@ data/inputs_aggregated.csv
 
 Every time the app starts, it computes a fingerprint (hash) of the CSV and compares it to the last known value. If they differ, meaning the CSV has been modified, it automatically regenerates all the data files used by the application before loading. You do not need to run anything manually.
 
-**Automatic method deactivation:** if a CDR method requires resources that the user has not added in Tab 1 (Resource inputs), the method is automatically disabled in Tabs 2 (Method constraints) and 4 (Optimization). A "Why is this method disabled?" indicator is shown next to the method. This is expected behavior — no data change is needed.
+**Automatic method deactivation:** if a CDR method requires resources that the user has not added in the Resource inputs tab, the method is automatically disabled in the Method constraints and Portfolio generation tabs. A "Why is this method disabled?" indicator is shown next to the method. This is expected behavior — no data change is needed.
+
+---
+
+### App tabs
+
+The app has seven tabs, accessible from the left sidebar:
+
+| Tab | Name | Purpose |
+|-----|------|---------|
+| Welcome | Welcome | Introduction, instructions, and a quick-start guide |
+| Resource inputs | Resource inputs | Set the available quantity of each resource; add custom resource batches |
+| Method constraints | Method constraints | Activate or deactivate CDR methods; set caps and constraints per method |
+| Resource coefficients | Resource coefficients | View and adjust the coefficient values (min / median / max) used by the optimizer |
+| Portfolio generation | Portfolio generation | Run the LP optimizer and view results (charts, tables, resource usage) |
+| Sensitivity analysis | Sensitivity analysis | Analyse how binding each resource constraint is; identify bottlenecks |
+| Scenario comparison | Scenario comparison | Save the current scenario, load a previous one, and compare multiple runs side by side |
+
+---
+
+### Custom resources
+
+In the **Resource inputs** tab, users can add custom resource batches — named resources that substitute for a standard or "Other" reference resource within a specific CDR method.
+
+For example, a user might add a batch called "Basalt A" linked to the reference group "Basalt mineral" and assign it to the Enhanced weathering method. The optimizer will then use the batch's custom coefficients instead of the standard reference values for that method.
+
+Custom batches are stored in the session and saved when exporting a scenario. They do **not** require any change to `inputs_aggregated.csv`.
+
+---
+
+### Scenarios (save and compare)
+
+In the **Scenario comparison** tab, users can:
+
+- **Export** the current state (resource caps, method constraints, coefficients, optimization results) as a `.zip` file or an Excel `.xlsx` file
+- **Import** a previously exported scenario file to restore a complete session state
+- **Compare** multiple saved scenarios side by side in the charts
+
+Scenario files are standalone and portable. Exporting a ZIP preserves the full state including custom resource batches; the Excel format covers the core results and can be opened directly in Excel.
+
+---
 
 There are two ways to update the data, depending on whether you are working directly on Hugging Face or on a local copy of the project:
 
@@ -205,12 +249,14 @@ Hugging Face will detect the push and rebuild the Space automatically.
 | File | What it is | Do you edit it? |
 |------|-----------|-----------------|
 | `data/inputs_aggregated.csv` | **Main data file**: all methods, resources and coefficients | ✅ Yes |
-| `data/update.py` | Script that regenerates everything from the CSV | ❌ No |
+| `data/tooltips.xlsx` | Tooltip texts shown on hover in the app | ✅ Yes |
+| `data/update.py` | Orchestration script: runs both generators below and updates the hash file | ❌ No |
+| `data/generate_model_data.py` | Generates `cost_sliders.json`, `method_groups.json`, `secondary_resources.json` from the CSV | ❌ No |
+| `data/generate_resource_template.py` | Generates `resource_template.xlsx` from the CSV | ❌ No |
 | `data/cost_sliders.json` | Auto-generated. Coefficients used by the app | ❌ No (auto) |
 | `data/method_groups.json` | Auto-generated. CDR method categories | ❌ No (auto) |
-| `data/secondary_resources.json` | Auto-generated. optional resource assignments | ❌ No (auto) |
+| `data/secondary_resources.json` | Auto-generated. Optional resource assignments | ❌ No (auto) |
 | `data/resource_template.xlsx` | Auto-generated. Excel template for users | ❌ No (auto) |
-| `data/tooltips.xlsx` | Tooltip texts shown on hover in the app | ✅ Yes |
 
 > ⚠️ **Never edit the auto-generated files directly**: your changes will be overwritten the next time `update.py` is run.
 
@@ -483,6 +529,40 @@ The `.xlsx` file cannot be edited inline on Hugging Face. Instead:
 
 ---
 
+### Case 9 - Remove a method or resource
+
+**When to use:** A CDR method or resource is no longer relevant and should be removed from the tool entirely.
+
+> ⚠️ If users have saved scenario files (`.xlsx` or `.zip`) that reference the removed method or resource, those fields will be silently ignored on load — no error is raised, but the data will be missing from the restored session.
+
+**Option 1 - On Hugging Face**
+
+1. Download `data/inputs_aggregated.csv` from the Files tab.
+2. Open it in Excel. Delete all rows where the `Implementation` column matches the method to remove, **or** all rows where the `Resource` column matches the resource to remove.
+   - To remove a method: delete every row for that `Implementation` value.
+   - To remove a resource from one method only: delete only the row(s) matching both the `Implementation` and `Resource`.
+   - To remove a resource entirely: delete every row where the `Resource` column matches, across all methods.
+3. Also open `data/tooltips.xlsx` and delete the corresponding row in the **Methods** or **Resources** sheet if a tooltip exists for the removed item.
+4. Upload both modified files via **Files** → `data/` → **+ Contribute** → **Upload Files** → Commit directly to main.
+5. Space restarts → check Logs for `Data files updated successfully.`
+
+**Option 2 - Locally**
+
+1. Open `data/inputs_aggregated.csv` and delete the relevant rows (see Option 1 above for which rows to target).
+2. Open `data/tooltips.xlsx` and delete the corresponding tooltip row if one exists. Save.
+3. Start the app to verify:
+   ```
+   streamlit run app.py
+   ```
+4. Commit and push:
+   ```
+   git add -A -- ':!venv/'
+   git commit -m "Remove [method name / resource name]"
+   git push
+   ```
+
+---
+
 ### Case 10 - Change the display order of methods or resources
 
 **When to use:** You want a method or resource group to appear earlier or later in the app (Resource inputs, Method constraints tabs...).