Merge pull request #1350 from marc-vdm/documentation

Move wiki to repo + Automated updating of wiki

.github/scripts/update_wiki.sh

@@ -0,0 +1,49 @@
+#! /bin/sh
+
+# input variables:
+# $1: commit message
+# $2: GH token ${{ secrets.GITHUB_TOKEN }}
+
+# clone the current wiki git
+cd ..
+git clone https://github.com/$GITHUB_REPOSITORY.wiki.git
+# extract the .git folder and empty the wiki folder
+mkdir temp
+yes | cp -rf activity-browser.wiki/.git temp
+find activity-browser.wiki -mindepth 1 -delete
+# copy the (potentially new) content from the main repo and the wiki .git folder to wiki folder and delete temp folder
+yes | cp -rf activity-browser/docs/wiki/* activity-browser.wiki/
+yes | cp -rf temp/.git activity-browser.wiki/
+rm -rf temp
+cd activity-browser.wiki
+# check if changes were made
+grep -lr "link:[a-zA-Z0-9_.-]*.asciidoc.*" .| xargs -r sed -i "s/.asciidoc//g"
+if git diff-index --quiet HEAD && [ ! -n "$(git status -s)" ]; then
+  # no changes
+  echo "Wiki documentation was not changed, documentation, not updating."
+  # return folders to original state
+  cd ..
+  rm -rf activity-browser.wiki
+  cd activity-browser
+  # exit script
+  set +e
+  pkill -9 -P $$ &> /dev/null || true
+  exit 0
+else
+  # changes
+  echo "Wiki documentation was changed, documentation, updating."
+  # set github user
+  git config --global user.name "$GITHUB_ACTOR"
+  git config --global user.email "$(git log -n 1 --pretty=format:%ae)"
+  # commit changes to wiki git
+  git status
+  git add .
+  git commit -m "$1"
+  # create origin and push
+  git remote add origin-wiki "https://$GITHUB_ACTOR:$2@github.com/$GITHUB_REPOSITORY.wiki"
+  git push origin-wiki master
+  # return folders to original state
+  cd ..
+  rm -rf activity-browser.wiki
+  cd activity-browser
+fi

.github/workflows/manual_update_wiki.yml

@@ -0,0 +1,12 @@
+name: manual update of wiki
+
+on:
+  workflow_dispatch:
+
+jobs:
+  update_wiki:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: update wiki
+        run: ./.github/scripts/update_wiki.sh "Manual wiki update for $GITHUB_REF_NAME" "${{ secrets.GITHUB_TOKEN }}"

.github/workflows/release.yaml

@@ -38,3 +38,5 @@ jobs:
         run: |
           anaconda -t ${{ secrets.CONDA_UPLOAD_TOKEN }} upload \
           /usr/share/miniconda/envs/build/conda-bld/noarch/*.tar.bz2
+      - name: Update wiki
+        run: ./.github/scripts/update_wiki.sh "Automated documentation update for $GITHUB_REF_NAME" "${{ secrets.GITHUB_TOKEN }}"

CONTRIBUTING.md

@@ -33,14 +33,30 @@ welcome!
 If you want to include the opening graphics created for the existing youtube videos, please 
 [contact the developers](https://github.com/LCA-ActivityBrowser/activity-browser#developers).
 
-### Github wiki page
+### Wiki
 The Activity Browser has its own
-[__wiki__](https://github.com/LCA-ActivityBrowser/activity-browser/wiki) page!
-This page contains an explanation (in text) of how to get started with the AB.
-
-Sadly, other than this, there is still very little to be found there. If you
-want to contribute to the wiki, either by adding figures or links or by writing
-new sections, please contact the developers!
+[__wiki__](https://github.com/LCA-ActivityBrowser/activity-browser/wiki).
+This page contains an explanation of how to get started with the AB.
+
+If you want to contribute to the wiki, either by adding figures or links or by writing
+new sections, please [contact the developers](https://github.com/LCA-ActivityBrowser/activity-browser#developers)! 
+
+#### Making changes to the wiki _(for developers)_
+Any images or other assets in the documentation should be stored in `docs/assets` and linked to there instead of 
+online links (unless copyrighted material is linked that cannot be shown in any other way).
+
+To make changes to the wiki, open a pull request with suggested changes to 
+[`docs/wiki`](https://github.com/LCA-ActivityBrowser/activity-browser/tree/main/activity_browser/docs/wiki).
+While contributors with write access to Activity Browser can directly change the wiki, <u>changes should instead be made
+to the files in `docs/wiki`</u> 
+([#1350](https://github.com/LCA-ActivityBrowser/activity-browser/pull/1350)).
+
+The wiki can be updated in of 2 ways:
+1. Merging a pull request and then manually
+[triggering the wiki update action](https://github.com/LCA-ActivityBrowser/activity-browser/actions/workflows/manual_update_wiki.yml).
+   - e.g. for fixing typos or making existing text clearer 
+2. When a new release is made, any changes will automatically be written to the wiki.
+   - e.g. for new text related to a new feature release, which should only be visible when the feature is available
 
 ### In-software guidance
 With more and more features being included into the AB, the inclusion of

activity_browser/docs/wiki/Global-Sensitivity-Analysis.md

@@ -0,0 +1,26 @@
+## 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
+[How to create a calculation setup](https://github.com/LCA-ActivityBrowser/activity-browser/wiki#creating-a-calculation-setup)
+
+## 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
+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. 
+* Finally, the user can **select to export both input and output data** to the GSA. If the user does not select this option, he will later only have the option to export the output data.
+
+![GSA setup](https://user-images.githubusercontent.com/33026150/115353675-164b7e00-a1b9-11eb-8063-dfca57e5d0b3.jpg)
+
+After the GSA is performed, the user will see a table with all input variables (environmental, economic flows, characterization factors and parameters) sorted by their delta value, which is the result of the GSA and characterizes their overall relevance. Additional data and metadata is also provided in the table.
+
+![GSA results only delta](https://user-images.githubusercontent.com/33026150/115353671-151a5100-a1b9-11eb-8218-544a5b00ebef.jpg)
+

activity_browser/docs/wiki/Home.md

@@ -0,0 +1,183 @@
+Welcome to the Activity Browser wiki!
+
+
+This page aims to explain how to get started using the Activity Browser to import and organize your data, construct and run simple LCA calculations, make changes to datasets and create simple parameterized systems.
+
+The Activity Browser (AB) is an open source LCA software that builds on top of the **Brightway** LCA framework. Users that are unfamiliar with Brightway2 are invited to also look at [the documentation of the framework](https://2.docs.brightway.dev/intro.html#main-brightway2-components), as this will explain a number of the components and terms used by AB.
+
+Please consider also watching our short AB [Youtube tutorials](https://www.youtube.com/channel/UCsyySKrzEMsRFsWW1Oz-6aA)
+
+
+## Contents
+
+* [Importing data](#importing-data)
+* [Creating a calculation setup](#creating-a-calculation-setup)
+* [Editing processes](#editing-processes)
+* [Creating parameters](#creating-parameters)
+
+## Importing data
+
+When starting in a new project the first thing to import is the 'default data',
+this data consists of the `biosphere3` database which contains a number of
+ standardized biosphere flows and a large amount of pre-made
+`Impact Categories` (Viewable in the 'Impact Categories' tab on the left).
+The button `Add default data (biosphere flows and impact categories)` will add
+these to the project.
+
+After this is done it becomes possible to create and import databases through the `New`
+and `Import` buttons next to the 'Databases:' header.
+
+With 'New' you can create a completely empty database with any given name and
+enter your own data as desired.
+
+Clicking 'Import' will open a new window that will allow you to select how you
+want to import data into brightway (and by extension, the Activity Browser).
+There are three main options: 'Ecoinvent', 'Forwast' and 'Local', see below for
+an in-depth explanation of these options.
+
+1. [Ecoinvent](https://www.ecoinvent.org/), a well-known and expansive life cycle inventory database.
+    * Download by login: This option will ask for a username and password and
+    will use these to attempt to login to the ecoinvent website. If this
+    succeeds you will be able to download the versions and kinds that are
+    available to the licence the username and password has.
+    * Local 7z-archive: This option expects that you have downloaded a version
+    of ecoinvent from their website before and will attempt to extract the
+    selected archive and import the data from there.
+    * Local directory: This option will directly read `ecospold2`
+    [format](https://www.ecoinvent.org/data-provider/data-provider-toolkit/ecospold2/ecospold2.html)
+    type files from the given directory and will attempt to import the data.
+      * Do note that this option will actually work with any other kind of dataset,
+      as long as it is using the ecospold2 format.
+2. [Forwast](https://lca-net.com/projects/show/forwast/), a publicly available
+dataset focussing on material stocks and waste amounts for the EU. Selecting
+this option will download the FORWAST dataset and import it into the project.
+3. Local brightway file ([BW2Package](https://2.docs.brightway.dev/technical/bw2io.html#bw2package)).
+This option allows for the import of databases previously exported from
+brightway, allowing for a straightforward way of sharing datasets between
+users.
+    * There are some validation steps when attempting to import data this way
+    and in the future these will be extended in an attempt to make this method
+    of database importing a lot more flexible to use.
+
+## Creating a calculation setup
+
+A calculation setup needs to be created in order to do LCA calculations. 
+
+![Calculation Setup](https://user-images.githubusercontent.com/33026150/115353679-177cab00-a1b9-11eb-920e-ac2f1c2c690f.jpg)
+
+You can find the `LCA Setup` tab on the right side of the window, opening it will
+show a number of buttons and a drop-down menu at the top. A new calculation setup
+can be created by clicking the `New` button. 
+
+After creating a new calculation setup you can drag-and-drop activities
+(technosphere processes) from their database list (Accessed by double-clicking
+on any database name) into the 'Reference Flows' table. Impact categories can
+be dragged-and-dropped from their list under the 'Impact Categories' tab into
+the 'Impact categories' table for the setup.
+
+A minimum LCA setup consists of 1 reference flow and 1 impact category. 
+
+## Editing processes
+
+Sometimes you want to quickly change a process to see what kind of influence some
+exchange has on the impact assessment of that functional unit, or to see if
+this change has some effect on the impact assessments of other downstream processes.
+
+Editing an activity can be done **only** when the database it belongs to is
+not in `read-only` mode, this mode is individually toggleable by clicking on
+the check-mark for the database in the databases table on the left side.
+**Take note however:** making an edit to any activity in a database will
+mark that database as 'dirty', but it won't keep track of the changes themselves.
+Keep this in mind when working with datasets such as ecoinvent.
+
+Editing an activity inside the activity browser is possible when viewing its
+details. Activity details can be seen by double-clicking on any _technosphere_
+activity (i.e. process) in a database, this will open the `Activity Details` tab
+on the right side of the window. After opening the details view of an activity,
+actually editing it requires checking the `Edit Activity` check-box inside the
+tab.
+
+It is possible to change a number of things about an activity: the `location`
+an activity occurs in, the `unit` of measurement for the product it produces,
+even the `product name` can be altered.
+
+Note that for the technosphere inputs and biosphere flows only the `amount` and
+`formula` fields can be edited, this is because only these fields have an
+actual effect on the assessment calculation.
+
+## Creating parameters
+
+Parameters are [special objects in Brightway](https://2.docs.brightway.dev/intro.html#parameterized-datasets)
+that allow users to create incredibly complex systems of interlocking parts.
+
+What parameters actually do is store a _value_ and allow recalculation of that
+value through a _formula_. While there are technically three layers of
+parameters (`Project`, `Database` and `Activity`), the AB encourages users to
+only use two (`Project` and `Activity`).
+
+Note that each parameter has a _name_ which is unique  within their 'group'.
+So project parameters have unique names within the project and activity
+parameters have names unique within their 'group'. The Activity Browser will
+strongly enforce this uniqueness and won't allow name changes if a conflict
+exists.
+
+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
+
+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
+can later be altered (renaming) by right-clicking on the parameter and
+selecting the `Rename parameter` option from the drop-down menu that opens.
+
+Both the _amount_ and _formula_ fields can be edited by double-clicking
+in them, though keep in mind that the _formula_ field has precedence when
+determining the _amount_ of the parameter.
+
+Finally, a (project) parameter can be deleted by right-clicking on the
+parameter and selecting the `Delete parameter` option from the drop-down
+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
+
+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
+to target the specific exchanges that exist within the activity that is
+parameterized.
+
+There are some rules for activity parameters:
+
+* Multiple parameters can be created for one activity.
+
+* Exchanges for activity B __cannot__ use parameters created for activity A.
+
+* Activity parameters must have a unique name __within__ the 'group' of the
+  related activity. Two parameters on __different__ activities can have the
+  same name.
+
+* If a project parameter and an activity parameter share a name, the activity
+  parameter will be preferred if that name is used in a formula for one of the
+  exchanges.
+
+In the Activity Browser activity parameters can be created in two ways:
+
+1. The first way is through dragging-and-dropping activities from the activities
+  table on the left side into the activity parameters table on the right side.
+  This allows for an easy way of parameterizing multiple activities at once.
+  However, the user still has to go into each activity (by way of the Activity
+  Detail tab) and parameterize the relevant exchanges.
+
+2. The second way is through directly parameterizing exchanges within the Activity
+  Detail tab (by editing the _formula_ field). As soon as an exchange formula is
+  stored, the Activity Browser will generate a new activity parameter for the 
+  related activity.
+
+Activity parameters can be `Renamed` and `Deleted` through right-clicking the
+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.
+

activity_browser/docs/wiki/Monte-Carlo-Simulation.md

@@ -0,0 +1,16 @@
+[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:
+1. To create a [calculation setup](https://github.com/LCA-ActivityBrowser/activity-browser/wiki#creating-a-calculation-setup) and perform a (static, i.e. non-stochastic) LCA. 
+2. Then the user should go to the `Monte Carlo` tab
+3. Then the following settings are available
+
+* Here the users needs to specify the number of **iterations** (we recommend to start with at least 100). 
+* A **random seed** can be determined, which can be used to reproduce the same random values again. 
+* Finally, the user interface provides the option for **including or excluding uncertainty information** at the level of the technology matrix (technosphere), the interventions matrix (biosphere), the characterization factors, and parameters (if any have been defined by the practitioner). 
+
+![Monte Carlo Simulation](https://user-images.githubusercontent.com/33026150/115353678-16e41480-a1b9-11eb-962e-9df0c7869d69.jpg)
+
+An example for Monte Carlo Simulation results are shown below.
+
+![Monte Carlo results](https://user-images.githubusercontent.com/33026150/115353677-16e41480-a1b9-11eb-8106-87f09b36991c.jpg)

setup.py

@@ -7,7 +7,7 @@
 root_dir = os.path.dirname(__file__)
 if root_dir:
     os.chdir(root_dir)
-accepted_filetypes = (".html", ".png", ".svg", ".js", ".css", ".txt", ".zip")
+accepted_filetypes = (".html", ".png", ".svg", ".js", ".css", ".txt", ".zip", ".md")
 
 for dirpath, dirnames, filenames in os.walk("activity_browser"):
     # Ignore dirnames that start with '.'