Quick start guide - kallitsis/ARIA GitHub Wiki

🚀 Quick start guide

This guide will help you set up and start using ARIA quickly. Running ARIA requires an active Ecoinvent license and an OpenAI API key.

🔹 Go to Purchasing OpenAI API Credits to learn more about how to set this up.

1️⃣ Setting up credentials

Before running ARIA, you need to create a credentials.py file on your local machine. This file is not included in the repository for security reasons, so you must create it manually.

steps to create `credentials.py`

Navigate to the ARIA project folder:
```
cd path/to/aria
```
Create a new file named credentials.py:
```
touch credentials.py
```
Open credentials.py with a text editor of your choice:
```
nano credentials.py
```
(or use vim, code for VS Code, or any preferred editor.)

Add the following content, replacing the placeholder values with your actual credentials:

# credentials.py  

ecoinvent_username = 'your_ecoinvent_username'
ecoinvent_password = 'your_ecoinvent_password'
openai_api_key = 'your_openai_api_key'

Save and close the file.

2️⃣ Securing your credentials

Since credentials.py contains sensitive information, you should ensure it is not accidentally uploaded.

steps to prevent accidental uploads

Add credentials.py to your .gitignore file:
```
echo "credentials.py" >> .gitignore
```
Verify that the file is ignored by running:
```
git status
```
The credentials.py file should not appear in the list of tracked files.

3️⃣ Setting up a brightway project

Once your credentials are set up, the next step is to initialise a Brightway project and load the Ecoinvent database.

Steps to set up a brightway project

Ensure you have installed all dependencies, including Brightway2.

Import the setup_brightway_project function from ARIA:

from ARIA.project_setup import setup_brightway_project

Define your preferred Ecoinvent version, system model, and project name:

# define your preferred settings  
project_name = "my brightway project"  # change this to your desired project name
ecoinvent_version = "3.10.1"           # change this to your preferred version
system_model = "cutoff"                # change this to "cutoff", "apos", or "consequential"

Initialise or load the Brightway2 project and Ecoinvent database:

ecoinvent_db = setup_brightway_project(project_name, ecoinvent_version, system_model)

Verify that the database has loaded successfully:

print(f"ecoinvent database '{ecoinvent_version} - {system_model}' loaded into project: {project_name}")

4️⃣ Loading data inputs from excel

Now that your Brightway project is set up, the next step is to load data inputs from an Excel file.

for macOS users

ARIA provides an AppleScript-based method to open Excel automatically.

steps to load data (macOS)

Import the necessary functions:

from ARIA.data_handling import open_excel_with_applescript, read_and_clean_excel

Define the path to your Excel file (update it to your actual path):

file_path = "/Users/your_username/Documents/GitHub/ARIA/Data_inputs.xlsx"

Open the file in Excel for editing:
```
open_excel_with_applescript(file_path)
```

Wait for the user to make edits, then continue:

input("after editing and saving the Excel file, press enter to continue...")

Read and clean the data from Excel:

data_frame = read_and_clean_excel(file_path, usecols="A:C", nrows="only_rows_that_include_data")

Print the imported data:

print("imported data:")
print(data_frame)

For windows users

macOS-specific AppleScript won't work on Windows, so you should open the Excel file manually before proceeding.

steps to load data (windows)

Open the Excel file manually:
- Locate the file at:
```
C:\Users\your_username\Documents\GitHub\ARIA\Data_inputs.xlsx
```
- Open it in Microsoft Excel.
Make necessary edits and save the file.

Run the following code to load the data:

from ARIA.data_handling import read_and_clean_excel

file_path = "C:/Users/your_username/Documents/GitHub/ARIA/Data_inputs.xlsx"

# read and clean data  
data_frame = read_and_clean_excel(file_path, usecols="A:C", nrows=12)

print("imported data:")
print(data_frame)

What this does

opens the Excel file for user input (automated on macOS, manual on Windows).
reads specific columns and rows from the file.
cleans the data and loads it into a pandas dataframe for further processing.

5️⃣ Initialising the openAI API client

Once the data inputs are loaded, the next step is to initialize the openAI API client.

steps to initialize the openAI client

Import the client creation function from ARIA:

from ARIA.openai_client import create_openai_client
from credentials import OPENAI_API_KEY as default_api_key

Initialise the openAI client using the API key stored in credentials.py:
```
client = create_openai_client(default_api_key)
```

this will allow ARIA to interact with openAI's API for various tasks. the client is now ready to be used in subsequent steps.

6️⃣ Running the analysis

once the data is loaded and the openAI API client is initialised, the final step is to run the analysis. this involves processing the data using ARIA’s search-and-select workflow.

steps to run the analysis

import search_workflow module

from ARIA.search_workflow import process_dataframe

run the search-and-select workflow

processed_df = process_dataframe(
    data_frame,
    db=db,
    client=openai,
    system_message="You are an LCA domain expert. Please pick the best match.", #Optionally, add specific information related to your goal and scope definition
    locations=["GLO", "RoW", "UK"] #Add any locations of focus based on Ecoinvent country codes
)

print the final dataframe with chatGPT results
```
print(processed_df.to_string(index=False))
```

What this does

loads the ecoinvent database into the brightway2 project.
configures the openAI API client.
reads the excel data inputs into a pandas dataframe.
processes the dataframe using ARIA’s search-and-select workflow.
outputs a final dataframe with chatGPT-generated results.

7️⃣ Processing the dataframe

after the initial analysis, the next step is to process the dataframe to refine and prepare the data for impact assessment.

steps to process the dataframe

import the required function

from ARIA.ecoinvent_processing import process_ecoinvent_dataframe

process the dataframe

processed_df = process_ecoinvent_dataframe(data_frame)

print the processed dataframe

print(processed_df.to_string(index=False))

What this does

cleans and processes the input dataframe.
structures the data for impact assessment.
prepares it for further LCA analysis.

8️⃣ Performing impact assessment

after processing the data, the next step is to run the life cycle impact assessment (LCIA).

steps to perform impact assessment

import required modules

from ARIA.impact_assessment import run_impact_assessment

define LCIA methods

lcia_method = [
    ('EF v3.1', 'climate change', 'global warming potential (GWP100)'),
    ('EF v3.1', 'material resources: metals/minerals', 'abiotic depletion potential (ADP)'),
    ('EF v3.1', 'water use', 'deprivation-weighted water consumption'),
    ('EF v3.1', 'acidification', 'accumulated exceedance (AE)'),
    ('EF v3.1', 'ecotoxicity: freshwater', 'comparative toxic unit for ecosystems (CTUe)'),
    ('EF v3.1', 'human toxicity: carcinogenic', 'comparative toxic unit for humans (CTUh)'),
    ('EF v3.1', 'ozone depletion', 'ozone depletion potential (ODP)'),
    ('EF v3.1', 'particulate matter formation', 'impact on human health'),
    ('EF v3.1', 'photochemical oxidant formation', 'tropospheric ozone increase'),
]

run the impact assessment

processed_df = run_impact_assessment(processed_df, lcia_method)

print the updated dataframe
```
print(processed_df)
```

what this does

applies life cycle impact assessment methods.
calculates environmental impact indicators.
updates the dataframe with impact results.

9️⃣ Visualising results

after performing the impact assessment, the final step is to visualise the results using waterfall charts.

steps to plot LCIA results

import the plotting function

from ARIA.plot_lcia import plot_lcia_waterfall_charts

run the visualization function

plot_lcia_waterfall_charts(processed_df)

What this does

generates waterfall charts for impact assessment results.
provides clear and structured visualizations of environmental impact indicators.
helps in interpreting and communicating LCA findings.

✅ With this final step, you have completed the full ARIA workflow! Your life cycle analysis results are now ready for interpretation and reporting.

Quick start guide - kallitsis/ARIA GitHub Wiki

🚀 Quick start guide

1️⃣ Setting up credentials

steps to create credentials.py

2️⃣ Securing your credentials

steps to prevent accidental uploads

3️⃣ Setting up a brightway project

Steps to set up a brightway project

4️⃣ Loading data inputs from excel

for macOS users

steps to load data (macOS)

For windows users

steps to load data (windows)

What this does

5️⃣ Initialising the openAI API client

steps to initialize the openAI client

6️⃣ Running the analysis

steps to run the analysis

What this does

7️⃣ Processing the dataframe

steps to process the dataframe

What this does

8️⃣ Performing impact assessment

steps to perform impact assessment

what this does

9️⃣ Visualising results

steps to plot LCIA results

What this does

steps to create `credentials.py`