Merge pull request #1381 from marc-vdm/lca_results_wiki

Styling updates + wiki page on contributions and sankey

activity_browser/docs/wiki/Flow-Scenarios.md

@@ -8,6 +8,6 @@
 
 [![Projects and Databases](https://img.youtube.com/vi/3LPcpV1G_jg/hqdefault.jpg)](https://www.youtube.com/watch?v=3LPcpV1G_jg)
 
-<sub>
+<sup>
 <b>Note:</b> some content of the video may be outdated. Written content should be more up-to-date.
-</sub>
+</sup>

activity_browser/docs/wiki/Getting-Started.md

@@ -25,10 +25,10 @@ Data in Brightway is organized into projects
 - Projects also contain other data, such as parameters and plugin settings.
 
 ![brightway organizational structure](./assets/brightway_org-scheme.png)
-<sub>
+<sup>
 _Image copied from the
 [Brightway documentation](https://docs.brightway.dev/en/latest/content/theory/structure.html#brightway-objects)._
-</sub>
+</sup>
 
 Read more about how data is organized in the 
 [Brightway documentation](https://docs.brightway.dev/en/latest/content/theory/structure.html#brightway-objects).
@@ -51,9 +51,9 @@ Finally, the menu bar at the top allows you to manage Activity Browser, Plugins
 
 [![Projects and Databases](https://img.youtube.com/vi/qWzaQjAf8ZU/hqdefault.jpg)](https://www.youtube.com/watch?v=qWzaQjAf8ZU)
 
-<sub>
+<sup>
 <b>Note:</b> some content of the video may be outdated. Written content should be more up-to-date.
-</sub>
+</sup>
 
 ### Installing a biosphere and impact categories
 In the `Project` tab there is initially a button called `Set up your project with default data`. 
@@ -127,9 +127,9 @@ ___
 
 [![Projects and Databases](https://img.youtube.com/vi/2rmydYdscJY/hqdefault.jpg)](https://www.youtube.com/watch?v=2rmydYdscJY)
 
-<sub>
+<sup>
 <b>Note:</b> some content of the video may be outdated. Written content should be more up-to-date.
-</sub>
+</sup>
 
 [Read more about activities...](Activities)
 
@@ -141,9 +141,9 @@ to be able to calculate results.
 
 [![LCA results](https://img.youtube.com/vi/J94UehVQM-Q/hqdefault.jpg)](https://www.youtube.com/watch?v=J94UehVQM-Q)
 
-<sub>
+<sup>
 <b>Note:</b> some content of the video may be outdated. Written content should be more up-to-date.
-</sub>
+</sup>
 
 [Read more about LCA calculation setups...](LCA-Calculation-Setups)
 

activity_browser/docs/wiki/Home.md

@@ -32,9 +32,9 @@ ___
 
 [![What is the Activity Browser video](https://img.youtube.com/vi/oeL_FOsNYfU/hqdefault.jpg)](https://www.youtube.com/watch?v=oeL_FOsNYfU)
 
-<sub>
+<sup>
 <b>Note:</b> some content of the video may be outdated. Written content should be more up-to-date.
-</sub>
+</sup>
 
 ___
 ## Documentation

activity_browser/docs/wiki/Installation-Guide.md

@@ -34,6 +34,10 @@ conda config --prepend channels conda-forge
 
 ## Installing Activity Browser
 You can now install Activity Browser by creating a python environment (`ab`)
+
+Depending on your computer and internet connection, it can take a while for this to complete.
+You will need to confirm that you really want to install the environment.
+
 ```bash
 conda create -n ab -c conda-forge activity-browser
 ```
@@ -53,3 +57,8 @@ These commands will update the Activity Browser and all of its dependencies in t
 conda activate ab
 conda update activity-browser
 ```
+
+> [!IMPORTANT]
+> If you currently have a version <u>below</u> `2.10.0`, please consult 
+> [this guide](https://github.com/LCA-ActivityBrowser/activity-browser/discussions/1049)
+> to update.

activity_browser/docs/wiki/LCA-Results.md

@@ -4,10 +4,132 @@
 > Please help us improve the wiki by reading our
 > [contributing guidelines](https://github.com/LCA-ActivityBrowser/activity-browser/blob/main/CONTRIBUTING.md#wiki).
 
-# Overview
+## Overview
 
-# Contribution Analysis
+### Inventory
 
-# Sankey
+### LCA overview results
 
-# Scenarios
+### Score matrix
+
+## Contribution Analysis
+### Differences between approaches
+Activity Browser has two contribution analysis approaches available to assess results, 
+`Elementary Flow (EF) Contributions` and `Process contributions`.
+
+Before we discuss the different approaches, we introduce a small example for the production of _'steel'_:
+
+![steel production example](./assets/steel_production_example.svg)
+
+The amounts we use are:
+
+| activity               | product            | technosphere exchanges          | biosphere exchanges      | 
+|------------------------|--------------------|---------------------------------|--------------------------|
+| coal production        | 10 kg coal         |                                 | 0.02 kg CH<sub>4</sub>   |
+| electricity production | 10 kWh electricity | 10 kg coal                      | 10.808 kg CO<sub>2</sub> |
+| steel production       | 10 kg steel        | 5 kWh electricity<br/>5 kg coal | 10 kg CO<sub>2</sub>     |
+
+<sup>
+<b>Note:</b> These numbers are used for ease of understanding, not for realism.
+</sup>
+
+To produce 1 kg of steel, we get a climate change impact of 1.6 kg CO2 eq with the _'IPCC 2021'_ impact category.
+In the way Brightway (and thus Activity Browser) calculate results, a _contribution matrix_ is calculated with 
+all impacts _from_ all EFs and all activities. 
+For the system and functional unit above, this would be:
+
+|                       | coal prod. | elec. prod. | steel prod. |
+|-----------------------|------------|-------------|-------------|
+| <b>CO<sub>2</sub></b> | -          | 0.5404...   | 1           |
+| <b>CH<sub>4</sub></b> | 0.0596...  | -           | -           |
+
+The _contribution matrix_ show the dis-aggregated results for each individual biosphere flow for each activity.
+
+#### EF contributions
+If we take sum the _rows_ to one row, we get the EF contributions 
+(the contribution of all CO<sub>2</sub> and CH<sub>4</sub> impacts together).
+In the case above, the EF contributions are:
+- CO<sub>2</sub>: 1.5404... (96.3%)
+- CH<sub>4</sub>: 0.0596... (3.7%)
+
+#### Process contributions
+If we take the sum of the _columns_ to one column, we get the process contributions
+(the contribution of all coal, electricity and steel production impacts together).
+In the case above, the process contributions are:
+- coal production: 0.0596... (3.7%)
+- electricity production: 0.5404... (62.5%)
+- steel production: 1 (33.8%)
+
+To summarize, the difference between EF and process contributions is the direction the contribution matrix is summed.
+
+### Manipulating results
+In this section we generalize a little bit for the different contribution approaches,
+we call the _from_ part of the contributions (the EFs or activities above) _entities_.
+
+There are several ways Activity Browser manipulates your results by default.
+- The results are **sorted** so that the largest (absolute) values are shown first
+- A `cut-off` of 5% is applied to group all entities with an impact below that value.
+- The contributions are _normalized_ to the impact of that reference flow, meaning they are show as a percentage, 
+  counting up to 100%
+
+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.
+![contributions cutoff](./assets/contribution_manipulation.png)
+
+#### Cut-off
+You can manually change the `cut-off` of the results in two ways, `Relative` or `Top #`.
+The `Relative` option shows contributions _from_ entities of _x_% or higher.
+The `Top #` options shows contributions from the _x_ entities that contribute the most (as absolute).
+
+You can change the value of the cut-off in the menu shown below.
+
+#### Compare
+The `Compare` menu allows you to compare different dimensions of results.
+You can compare between:
+- _Reference flows_
+- _Impact categories_
+- _Scenarios_ (only available in scenario LCA, see [scenarios](#scenarios))
+
+The compare mode defines what is shown in the figure.
+
+#### Aggregation
+The `Aggregate by` menu can be used to _group_ results based on field names.
+As an example, EF contributions can be grouped on the name, 
+for example to group all flows with the same name.
+Another example for process contributions can be grouped based on their reference product name.
+
+#### Plot and Table
+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.
+The `Relative` results will sum to 100%, the `Absolute` results will sum to the impact score.
+
+## 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).
+
+### Sankey configuration
+In the `Sankey` tab, you can configure, you can set the 
+Reference flow, Impact category and Scenario (only available in scenario LCA, see [scenarios](#scenarios)) to be shown.
+you can also set a `cutoff` and `calculation depth` setting.
+
+The `cutoff` setting will stop traversing the supply chain once the impact is below the percentage specified.
+The `calculation depth` will stop traversing the supply chain once that number of calculations have been performed.
+
+### Sankey results
+In the Sankey, the red arrows show the _cumulative_ impact of the _product_ flow 
+(_direct_ from that process and _indirect_ from all upstream processes involved in producing that product), 
+the boxes show the _direct_ (process contribution) impact of that process.
+
+Using the example above in the [contribution analysis](#contribution-analysis) section, we show the sankey below.
+The [process contribution](#process-contributions) results are also shown in the boxes below.
+
+![sankey example](./assets/sankey_example.svg)
+
+## Other Results tabs
+The Monte Carlo and Senstivity Analysis tabs are explained on the [Uncertainty](Uncertainty) page.
+
+## Scenarios

activity_browser/docs/wiki/Parameters.md

@@ -4,9 +4,9 @@
 > Please help us improve the wiki by reading our
 > [contributing guidelines](https://github.com/LCA-ActivityBrowser/activity-browser/blob/main/CONTRIBUTING.md#wiki).
 
-# General concepts
+## General concepts
 
-# Creating parameters
+## Creating parameters
 
 Parameters are 
 [special objects in Brightway](https://docs.brightway.dev/en/latest/content/api/bw2data/parameters/index.html)
@@ -27,7 +27,7 @@ The reason for this uniqueness is that a parameter _name_ can be used in
 _formulas_ to insert the _value_ of that parameter at that specific place
 in the _formula_.
 
-## Project parameters
+### Project parameters
 
 A new project parameter can be created by clicking the `New` button next
 to the 'Project' label. A default name is assigned to this parameter which
@@ -44,7 +44,7 @@ menu. Do note however that a parameter can __only__ be deleted if it is
 not being used in any other _formula_ field, if the Activity Browser finds
 that this __is__ the case, the `Delete` option will be grayed out.
 
-## Activity Parameters
+### Activity Parameters
 
 Where project parameters can be used by any formula anywhere in the project,
 activity parameters are a lot more narrow in scope. These parameters are made
@@ -83,4 +83,4 @@ parameter, much the same as project parameters. Additionally, the Activity
 Detail tab can be opened for the parameterized activity by way of the
 `Open activities` option.
 
-# Scenarios
+## Scenarios

activity_browser/docs/wiki/Plugins.md

@@ -5,7 +5,7 @@ The plugin code has been designed and written by [Remy le Calloch](https://githu
 (supported by [G-SCOP laboratories](https://g-scop.grenoble-inp.fr/en/laboratory/g-scop-laboratory)) 
 with revisions from the Activity Browser.
 
-# Available plugins
+## Available plugins
 > [!CAUTION]
 > Plugins are not always developed by Activity Browser maintainers. 
 > Below are listed plugins from people we know but we do not verify plugins. 
@@ -19,11 +19,11 @@ with revisions from the Activity Browser.
 | [Notebook](https://github.com/Pan6ora/ab-plugin-Notebook)               | Use Jupyter notebooks from AB                                                                                                                      | [anaconda](https://anaconda.org/pan6ora/ab-plugin-template), [github](https://github.com/Pan6ora/ab-plugin-Notebook)                                                            | Rémy Le Calloch                     |
 | [template](https://github.com/Pan6ora/activity-browser-plugin-template) | An empty plugin to start from                                                                                                                      | [anaconda](https://anaconda.org/pan6ora/ab-plugin-template), [github](https://github.com/Pan6ora/activity-browser-plugin-template)                                              | Rémy Le Calloch                     |
 
-# Installation
-## Detailed instructions
+## Installation
+### Detailed instructions
 Every plugin's webpage (links are provided in the above table) should have a **Get this plugin** section with installation instructions.
 
-## General instructions
+### General instructions
 Plugins are often conda packages (like the Activity Browser). 
 To add a plugin, install it in your conda environment.
 
@@ -35,26 +35,26 @@ To add a plugin, install it in your conda environment.
 > conda install -c pan6ora -c conda-forge ab-plugin-notebook
 > ```
 
-# Usage
+## Usage
 Once a new plugin is installed restart the Activity Browser.
 
 > [!IMPORTANT]
 > If you need help using a plugin or experience problems when using a plugin,
 > contact the developers of the plugin, the Activity Browser team cannot help you.
 
-## Enabling a plugin
+### Enabling a plugin
 Plugins are enabled **per project**. 
 Simply open the plugin manager in the `Tools > Plugins` menu. 
 Select the plugins you want to use and close the plugin manager. 
 New tabs should have appeared in Activity Browser for each plugin.
 
-## Disabling a plugin
+### Disabling a plugin
 Disable a plugin the same way you activated it.
 
 > [!WARNING]
 > Keep in mind that all data created by the plugin in a project could be erased when you disable it.
 
-# Developing a plugin
+## Developing a plugin
 > [!IMPORTANT]
 > The plugin system is still in development so keep in mind that things may change at any point.
 

activity_browser/docs/wiki/Uncertainty.md

@@ -4,10 +4,10 @@
 > Please help us improve the wiki by reading our
 > [contributing guidelines](https://github.com/LCA-ActivityBrowser/activity-browser/blob/main/CONTRIBUTING.md#wiki).
 
-# Uncertainty
+## Uncertainty
 
 ___
-# Monte Carlo simulation
+## Monte Carlo simulation
 [Monte Carlo Simulation](https://en.wikipedia.org/wiki/Monte_Carlo_method) is method that relies on repeated random sampling of data to produce numerical results for uncertain input data. In LCA, economic and environmental flows as well as other data such as characterization factors or parameters may include uncertainty information (e.g. mathematical distributions or pedigree scores). During Monte Carlo simulation, random samples of this data are generated to calculate LCA results. 
 
 In the Activity Browser, Monte Carlo Simulation can be used. The **steps **for this are:
@@ -26,22 +26,22 @@ An example for Monte Carlo Simulation results are shown below.
 ![monte carlo results](./assets/monte_carlo_results.jpg)
 
 ___
-# Global Sensitivity Analysis
-## Overview
+## Global Sensitivity Analysis
+### Overview
 Global Sensitivity Analysis (GSA) is a family of methods that aim to determine which input variables are contributing the most to variations in the outcome of a stochastic model. In the context of Life Cycle Assessment (LCA), this means that GSA aims at identifying those variables (e.g. economic flows, environmental flows, characterization factors, or parameters) that due to their uncertainty distributions affect LCA results most. This provides the LCA practitioner with a shortlist of important variables for his model. For some of these variables, it may be possible to collect additional data to reduce uncertainties, which may then reduce the overall uncertainties of the LCA results. 
 
 The **AB implements the delta-moment independent method** to calculate the global sensitivities. The approach is described in detail in our [scientific paper](https://onlinelibrary.wiley.com/doi/10.1111/jiec.13194). Our implementation uses the Sensitivity Analysis Library [SALib](https://github.com/SALib/SALib).
 
 Here we describe the basic steps for performing GSA with the Activity Browser. 
 
 
-## Step 1: creating a calculation setup and calculating LCA results
+### Step 1: creating a calculation setup and calculating LCA results
 [How to create a calculation setup](https://github.com/LCA-ActivityBrowser/activity-browser/wiki#creating-a-calculation-setup)
 
-## Step 2: performing Monte Carlo Simulation
+### Step 2: performing Monte Carlo Simulation
 Monte Carlo simulation needs to be performed in order to obtain sampled data for the LCA inputs (economic and environmental flows, characterization factors, and parameters) and the corresponding LCA results, which, together, form the required input data for the GSA. A description of how to perform Monte Carlo Simulation in the AB is provided [here](https://github.com/LCA-ActivityBrowser/activity-browser/wiki/Monte-Carlo-Simulation).
 
-## Step 3: Global Sensitivity Analysis
+### Step 3: Global Sensitivity Analysis
 Now the user can go to the `Sensitivity Analysis` tab to perform GSA. The figure below shows the options the user has at this level. 
 * While the Monte Carlo Simulation was performed for all reference flows and impact categories at once, the GSA is performed for one reference flow and impact category at a time. This means that the user needs to **select the reference flow and impact categories** that he is interested in. GSA can be repeated later for other reference flows or impact categories based on the same Monte Carlo Simulation results. 
 * The user can specify the **cut-off values **used for flows in the A (technosphere) and B (biosphere) matrices.