Skip to content

Latest commit

 

History

History
211 lines (135 loc) · 7.74 KB

README.md

File metadata and controls

211 lines (135 loc) · 7.74 KB

SQAaaS badge

SQAaaS badge shields.io

DOI

Elicipy

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

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 (https://github.com/demichie/elicipy) 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 "Yup, I have an app" 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. Click on "Advanced settings".

  6. Select Python version 3.9 or 3.10.

  7. In the Secrets textbox write.

    github_token = "insert_here_your_token"

  8. 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 = ''

SMTP_SERVER_ADDRESS = ''

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 = ''

SMTP_SERVER_ADDRESS = ''

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 'local_github') and fill the RepositoryData field (with the new github repository for the answers), the user filed and the github_token_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 = ''

SMTP_SERVER_ADDRESS = ''

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.

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:

python elicipy.py

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:

python elicipy.py

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:

python elicipy.py

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 the code was supported by the project PIANETA DINAMICO, Istituto Nazionale di Geofisica e Vulcanologia, Italy.