Elicipy 2

Elicipy is an Expert elicitation Python tool, aimed at both the collection of anwers from the epxerts with a webform and their analysis.

The answers (for both seed and target questions) are collected with a Streamlit webapp, that can run locally or from streamlit.io (read below).

The analysis is always done locally.

All the elicitation data, included the input files for the creation of the webapp and for analysis, are in subfolders of the ELICITATIONS folder. The files required to run an elicitation are:

1. createWebformDict.py
2. elicipyDict.py
3. DATA/questionnaire.csv

When there are multiple elicitations folders inside ELICITATION, the elicitation for the Webapp is specified in the file ElicitationCase.py

Installation

To install Elicipy, first create a pip or anaconda environement with Python >=3.10.

Then, activate the environment, download a copy of the repository and unzip it.

From the command line, go to the main folder of elicipy and type:

pip install .

This will install elicipy and the two main executables:

1. elicipy-form (for the collection of answers with a webform).
2. elicipy (for the analysis of the answers).
3. elicipy-dashboard (after the analysis, for the the interactive visualization of the results).

---

Webform

Webapp hosted on streamlit.io

Here there are steps to install and run the webapp from streamlit.io.

On Github, you need two repositories, one to collect the answers and on hosting the webapp streamlit_app.py.

GITHUB STREAMLIT REPOSITORY

1. To create the new repository for the answers, go to the you github main page, click on the tab "Repositories", and then on the green button "New", on the top-right above the list of your repositories. Write the "Repository name" for your asnwer repository, set this repository to "Private" if you don't want to show the answers, and finally click on "Create repository" at the bottom.
2. Go to the Elicipy repository and create a copy of the repository by clicking on the green button "Use this template" on the top-right and selecting "Create a new repository". Input the name of the new repository and click on the green button "Create repository" at bottom of the page.
3. Edit in the input file createWebformDict.py the fields datarepo (set to 'github') and the RepositoryData (with the new github repository for the answers).
4. Set in the input file createWebformDict.py the quest_type variable to "seed" of "target".
5. Edit the csv file with your questions in the DATA folder of the github repository for the webapp (see the questionnaire.csv file for an example of the format).
6. In the ELICITATIONS folder, edit the file "ElicitationCase.py" with the elicitation folder name.
7. Click on the top-right (on your github user icon), and from the menu click on "Settings".
8. At the bottom of the left panel, click on "Developer settings".
9. On the left, click on "Personal access tokens".
10. Click on "Tokens (classic)".
11. Click on top on "Generate new token" and select (Generate new token (classic)).
12. Give a name.
13. Select scope "repo".
14. At the end of the page click on "Generate token".
15. Copy the newly generated token. You will use it as Streamlit Secret.

STREAMLIT

1. Login with github account.
2. On the top-right, click on "Create app".
3. Select "Deploy a Public app form GitHub" by clicking on "Deply now" to deploy the app from the github repository.
4. In the "Repository" field, select the github repository for the webapp (i.e. the repository you generated from the template).
5. In the "Main file path", select the file "elicipy/streamlit_app.py".
6. Click on "Advanced settings".
7. Select Python version 3.10.
8. In the Secrets textbox write.

githubtoken = "inserthereyourtoken"

1. If you want to send a confirmation email after the answers are submitted, in the file createWebformDict.py set confirmation_mail = True and add the following lines in the Secrets texbox (fill with your email data).

SENDER_ADDRESS = ''

SENDER_NAME = ''

SENDER_PASSWORD = ''

SMTPSERVERADDRESS = ''

PORT =

1. Click on "Save".
2. Click on "Deploy".

Now you should see your webform, and on the top-right you can click on "Share" to get the link.

Webapp running locally with data saved locally

1. Edit in the input file createWebformDict.py the fields datarepo (set to 'local').
2. If you want to send a confirmation email after the answers are submitted, in the file createWebformDict.py set confirmation_mail = True and add the following lines (fill with your email data).

SENDER_ADDRESS = ''

SENDER_NAME = ''

SENDER_PASSWORD = ''

SMTPSERVERADDRESS = ''

PORT =

1. Edit the file "ElicitationCase.py" with the elicitation folder name.
2. Start the webapp with:

streamlit run streamlit_app.py

On your screen you will see these lines (with different web addresses):

``` You can now view your Streamlit app in your browser.

Local URL: http://localhost:8501

Network URL: http://10.246.1.121:8501 ```

The "Network URL" is the link to share.

Webapp running locally with data saved on Github

1. On Github, you need a repository to collect the answers (create a new repository).
2. Click on the top-right (on your github user icon), and from the menu click on "Settings".
3. At the bottom of the left panel, click on "Developer settings".
4. On the left, click on "Personal access tokens".
5. Click on "Tokens (classic)".
6. Click on top on "Generate new token" and select (Generate new token (classic).
7. Give a name.
8. Select scope "Repo".
9. At the end of the page click on "Generate token".
10. Copy the newly generated token.
11. On your computer, edit in the input file createWebformDict.py the fields datarepo (set to 'localgithub') and fill the RepositoryData field (with the new github repository for the answers), the user filed and the githubtoken_field.
12. If you want to send a confirmation email after the answers are submitted, in the file createWebformDict.py set confirmation_mail = True and add the following lines (fill with your email data).

SENDER_ADDRESS = ''

SENDER_NAME = ''

SENDER_PASSWORD = ''

SMTPSERVERADDRESS = ''

PORT =

1. Edit the file "ElicitationCase.py" with the elicitation folder name
2. Start the webapp with:

elicipy_form

On your screen you will see these lines (with different web addresses):

``` You can now view your Streamlit app in your browser.

Local URL: http://localhost:8501 Network URL: http://10.246.1.121:8501 ```

The "Network URL" is the link to share.

Password protected form

If you want to access the form with a password, first add the following line in the file createWebformDict.py:

password_protected = True

Then, run the script generate_hash.py from the elicipy folder:

python generate_hash.py

You will see on screen your hashed password.

Your hashed password (store this in .env or secrets.toml): $2b$12$e.TWWrtWDuEfYaU7oe8RR.yUX4fOdJeA4N8flaMNnzIzte3Xqlxay

Now create in the elicpy2 main folder a file .env, and add the following line to the file, replacing the passowrd_hash with that generated by the script:

PASSWORD_HASH=$2b$12$e.TWWrtWDuEfYaU7oe8RR.yUX4fOdJeA4N8flaMNnzIzte3Xqlxay

At this point, when you open the form webpage on a browser, you will be asked for the password first.

---

Analysis

Analysis with Webapp hosted on streamlit.io

1. Copy the elicitation folder containing DATA from the ELICITATIONS folder of the Webapp repository to the ELICITATIONS folder on your computer
2. On your computer, in the file ElicipyDict.py, set datarepo = 'github' and RepositoryData = the name of the Github repository with the answers
3. Set the analysis parameter as desired.
4. run the Python analysis script:

elicipy

Analysis with Webapp hosted locally and answers saved on Github

1. On your computer, in the file ElicipyDict.py, set datarepo = 'github' and RepositoryData = the name of the Github repository with the answers
2. Set the analysis parameter as desired.
3. run the Python analysis script:

elicipy

Analysis with Webapp hosted locally and answers saved locally

1. In ElicipyDict.py set datarepo = 'local'
2. Set the analysis parameter as desired.
3. run the Python analysis script:

elicipy

The analysis results are saved in the folder output_dir (set in ElicipyDict.py)

---

Authors:

• Mattia de' Michieli Vitturi.
• Andrea Bevilacqua.
• Alessandro Tadini.
• Augusto Neri.

Some of the functions are based on the scripts of the Matlab package Anduril (authors: Georgios Leontaris and Oswaldo Morales-Napoles).

The development of ELICIPY was supported by the project “Pianeta Dinamico - Working Earth”– Theme: WUNDERVUL “Toward a Wider Understanding of Vulcano”, funded by the Italian Ministry of Education, University and Research, by the “Convenzione Attuativa per il potenziamento delle attività di servizio” funded by the Italian Department of Civil Protection, and by the Project “Hazard and risk assessment for Kolumbo Volcano, Greece”, funded by the Hellenic Survey of Geology and Mineral Exploration (HSGME).