Update wiki documentation and add help buttons to contribution tabs

activity_browser/docs/wiki/LCA-Results.md

@@ -100,14 +100,15 @@ we call the _from_ part of the contributions (the EFs or activities or FT above)
 
 There are several ways Activity Browser manipulates your results by default.
 - The results are **sorted** so that the row with the largest (absolute) average values are shown first.
-- A `cut-off` of 5% is applied, this only shows results that contribute at least 5% to the total result, 
+- A `cut-off` of 5% is applied, this only shows results that contribute at least 5% to the total range of results, 
   all other entities are grouped into a `Rest (+)` or `Rest (-)` groups.
 - The contributions are _normalized_ to the impact of that reference flow, meaning they are show as a percentage, 
   counting up to 100% for every item you compare.
 
 These actions are taken to show you the most relevant results.
 
-You can manually manipulate the contribution results in the next menu, which we explain bit by bit below.
+You can manually manipulate the contribution results in the menu shown below, which we will explain bit by bit 
+in the next sections.
 ![contributions cutoff](./assets/contribution_manipulation.png)
 
 #### Cut-off
@@ -139,9 +140,19 @@ By default, Activity Browser shows a plot and a table.
 You can disable one of them if you want to focus on one of them.
 
 #### Relative and Absolute
-Finally, you can choose between `Relative` and `Absolute` results.
+You can choose between `Relative` and `Absolute` results.
 The `Relative` results will sum to 100% (the total score), the `Absolute` results will sum to the impact score.
 
+#### Range and Score
+If the Cut-off type is `Relative`, you can choose between `Range` and `Score`.
+This determines what you use as the _total_ to which the relative contributions are counted. 
+For `Range`, this is the full _range_ of results, for example, if all your negative results together have a score of -2
+and all your positive results together have a score of 10, the _range_ is 12 (-2 * -1 + 10).
+For `Score`, this is the total score (sum) of the results, for example, if all your negative results together have a 
+score of -2 and all your positive results together have a score of 10, the _score_ is 8 (-2 + 10).
+The `Range` or `Score` setting are only used when 1) your Cut-off type is `Relative` 
+and 2) your results contain both positive and negative results.
+
 ### Positive and negative numbers in contribution results
 It can happen in LCA that you get both positive and negative numbers in your contribution results.
 Some of these reasons could be negative characterization factors, flows with negative numbers or using substitution flows.
@@ -153,16 +164,6 @@ Below is a simple example (with unrealistic values) to demonstrate this:
 
 ![CA example with positive and negative results](./assets/ca_positive_negative_example.png)
 
-Other softwares (e.g. [Brightway2-Analyzer](https://github.com/brightway-lca/brightway2-analyzer)) 
-may use a different 'total', meaning the contributions may look different.
-For example, Brightway2-Analyzer uses the total of absolute values 
-(so the range of numbers from the lowest negative number to the highest positive number) as 100% of the score.
-
-> [!IMPORTANT]
-> Due to Activity Browser using 100% as the 'total' when you sum all positive contributions, 
-> positive results will sum to over 100% when there are also negative numbers, which will sum together to 100%.
-> Even single contributions may be over 100%. 
-
 ## Sankey
 The `Sankey` tab shows results from [graph traversal](https://docs.brightway.dev/projects/graphtools/en/latest/index.html).
 Graph traversal calculates results step-by-step for _nodes_ (activites) in the _graph_ (supply chain/product system).

activity_browser/layouts/tabs/LCA_results_tabs.py

@@ -6,6 +6,7 @@
 
 from collections import namedtuple
 from copy import deepcopy
+from termios import VLNEXT
 from typing import List, Optional, Union
 from logging import getLogger
 
@@ -19,7 +20,6 @@
                                QPushButton, QRadioButton, QScrollArea,
                                QTableView, QTabWidget, QToolBar, QVBoxLayout,
                                QWidget)
-from openpyxl.styles.builtins import percent
 
 from activity_browser.bwutils import AB_metadata
 
@@ -53,6 +53,16 @@ def get_header_layout(header_text: str) -> QVBoxLayout:
     vlayout.addWidget(horizontal_line())
     return vlayout
 
+def get_header_layout_w_help(header_text: str, help_widget) -> QVBoxLayout:
+    hlayout = QHBoxLayout()
+    hlayout.addWidget(header(header_text))
+    hlayout.addWidget(help_widget)
+    hlayout.setStretch(0, 1)
+
+    vlayout = QVBoxLayout()
+    vlayout.addLayout(hlayout)
+    vlayout.addWidget(horizontal_line())
+    return vlayout
 
 def get_unit(method: tuple, relative: bool = False) -> str:
     """Get the unit for plot axis naming.
@@ -236,6 +246,9 @@ class NewAnalysisTab(BaseRightTab):
 
     def __init__(self, parent=None):
         super().__init__(parent)
+
+        self.help_button: Optional[QToolBar] = None
+
         self.parent = parent
         self.has_scenarios = self.parent.has_scenarios
 
@@ -954,6 +967,24 @@ def __init__(self, parent, **kwargs):
 
         self.has_been_opened = False
 
+        # set-up the help button
+        self.explain_text = """
+                <p>There are three ways of doing Contribtion Analysis in Activity Browser:</h4>
+                <p>- <b>Elementary Flow (EF) Contributions</b></p>
+                <p>- <b>Process Contributions</b></p>
+                <p>- <b>First Tier (FT) Contributions</b></p>
+                
+                Detailed information on the different approaches provided in this <a href="https://github.com/LCA-ActivityBrowser/activity-browser/wiki/LCA-Results#contribution-analysis">wiki page</a> about the different approaches. 
+
+                <p>You can manipulate the results in many ways with Activity Browser, read more on this <a href="https://github.com/LCA-ActivityBrowser/activity-browser/wiki/LCA-Results#manipulating-results">wiki page</a>
+                about manipulating results. 
+                """
+
+        self.help_button = QToolBar(self)
+        self.help_button.addAction(
+            qicons.question, "Left click for help on Contribution Analysis Functions", self.explanation
+        )
+
     def set_filename(self, optional_fields: dict = None):
         """Given a dictionary of fields, put together a usable filename for the plot and table."""
         optional = optional_fields or {}
@@ -1135,7 +1166,8 @@ class ElementaryFlowContributionTab(ContributionTab):
     def __init__(self, parent=None):
         super().__init__(parent)
 
-        self.layout.addLayout(get_header_layout("Elementary Flow Contributions"))
+        header = get_header_layout_w_help("Elementary Flow Contributions", self.help_button)
+        self.layout.addLayout(header)
         self.layout.addWidget(self.cutoff_menu)
         self.layout.addWidget(horizontal_line())
         combobox = self.build_combobox(has_method=True, has_func=True)
@@ -1188,7 +1220,8 @@ class ProcessContributionsTab(ContributionTab):
     def __init__(self, parent=None):
         super().__init__(parent)
 
-        self.layout.addLayout(get_header_layout("Process Contributions"))
+        header = get_header_layout_w_help("Process Contributions", self.help_button)
+        self.layout.addLayout(header)
         self.layout.addWidget(self.cutoff_menu)
         self.layout.addWidget(horizontal_line())
         combobox = self.build_combobox(has_method=True, has_func=True)
@@ -1255,7 +1288,8 @@ def __init__(self, cs_name, parent=None):
         # we also cache totals, not for calculation speed, but to be able to easily convert for relative results
         self.caching = True  # set to False to disable caching for debug
 
-        self.layout.addLayout(get_header_layout("First Tier Contributions"))
+        header = get_header_layout_w_help("First Tier Contributions", self.help_button)
+        self.layout.addLayout(header)
         self.layout.addWidget(self.cutoff_menu)
         self.layout.addWidget(horizontal_line())
         combobox = self.build_combobox(has_method=True, has_func=True)