README.md

---
title: BSAT
emoji: 👁
colorFrom: purple
colorTo: indigo
sdk: streamlit
sdk_version: 1.44.1
app_file: app.py
pinned: false
---

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

# USDA Agricultural Trade Scenario Dashboard

This dashboard allows users to explore how different policy scenarios impact agricultural trade metrics across regions and commodities.

This project was initially developed for USDA Baseline Agricultural Trade (BSAT) research, but it is also accessible to the general public for demonstration and learning purposes.

---

## 1. How to Use the Dashboard

- **Step 1: Upload Model Outputs**  
  Upload **one or two** ZIP files. Each file must contain:
  - Baseline data (`baseline_projections.csv` or `data_targets_adjusted.csv`)
  - Scenario solution data (`data_scenario_solution_*.csv` or `data_solution.csv`)
  - Optionally, Metadata (`METADATA.csv`) and Shock Variables (`data_shocks.csv`) will also be automatically recognized and displayed.

- **Step 2: Explore Visualizations**  

  - **Line Charts**: Time series comparison between baseline and shock scenarios.
  - **Top # Bar Charts**: Largest changes by region for selected metrics.
  - **Scenario Comparison Bars**: Side-by-side shock comparison by region.
  - **Heatmaps**: Yearly percent changes across regions and commodities.
  - **Correlation Matrix**: Attribute interdependence within a region over time.


- **Step 3: Interact with Charts**

  - Select region, commodity, attribute, and year using dropdowns or sliders.
  - Toggle between Shock 1 and Shock 2 in applicable charts (line, bar, heatmap).
  - In Top # Bar Charts, choose how many regions to display and sort by largest changes.
  - In Correlation Matrix, select year range and explore attribute relationships over time.
  - Apply filters to shock variable tables to focus on specific policies or affected regions.
  - Hover for detailed tooltips; use legends to highlight specific shock comparisons.
---

## 2. About Hugging Face Hosting

This dashboard is currently hosted on [Hugging Face Spaces](https://huggingface.co/spaces), a platform that allows easy deployment of machine learning and data applications through web interfaces.

- **Technical Details**:
  - The dashboard is built using **Python** and **Streamlit**.
  - Hugging Face handles hosting, storage, and runtime in containerized environments.
  - Each time a user interacts, the app runs live in an isolated environment with limited resources (RAM, storage, CPU).

- **Security Considerations**:
  - Uploaded files are temporarily stored in memory and automatically cleared after sessions expire.
  - No uploaded data is shared publicly or permanently stored on Hugging Face servers unless explicitly coded otherwise (this dashboard does **not** save any data).

---

## 3. Running the Dashboard Locally (For Internal Use)

If USDA would prefer to run this dashboard **within its own servers** or **on a local machine**, it can be easily set up:

**Requirements**:
- Python 3.8+
- Pip
- Streamlit (v1.18.0+ recommended)
- Other libraries: `pandas`, `altair`, `matplotlib`, `seaborn`, `numpy`

## How to Run This Dashboard Locally on macOS

If you'd like to run this dashboard on your own machine (e.g., for internal USDA use), follow these steps on a Mac:

### Step 1: Installing Python

Open Terminal and enter the following command to check if it is installed:
```bash
python3 --version
```
If a version number is returned (e.g. Python 3.10.6), you can skip this step.If not:

Paste the following command. It will prompt you for your **Mac password**—note that when typing your password, **nothing will appear**, but it is being recorded. Just press Enter when done.

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
Install Python using Homebrew:

```bash
brew install python
```
### Creating Project Folders

```bash
mkdir my_dashboard
cd my_dashboard
```
Put a Python script, say called app.py, into this folder.
### Step 3: Creating and activating a virtual environment

```bash
python3 -m venv venv
source venv/bin/activate
```

To exit the virtual environment at any time:

```bash
deactivate
```

### Step 4: Installing Streamlit and Dependencies

```bash
pip install streamlit pandas altair matplotlib seaborn
```

### Step 5: Run the Streamlit application

```bash
streamlit run app.py
```

Visit `http://localhost:8501` in your browser to interact with the dashboard.

---

# How to Run This Dashboard Locally on Windows

If you'd like to run this dashboard on your own Windows machine (e.g., for internal use), follow these steps:

## Step 1: Installing Python

First, check if Python is installed.

Open **Command Prompt** (search for "cmd") and type:

```bash
python --version
```

If you see a version number like Python 3.x.x, you can skip installation. Otherwise:

- Go to the [official Python website](https://www.python.org/downloads/windows/)
- Download and install Python (make sure to check **"Add Python to PATH"** during installation!)

## Step 2: Creating a Project Folder

Open **Command Prompt** and create a working folder:

```bash
mkdir my_dashboard
cd my_dashboard
```

Place your Python script (e.g., `app.py`) inside this `my_dashboard` folder.

## Step 3: Creating and Activating a Virtual Environment

In the **Command Prompt** (inside the `my_dashboard` folder):

```bash
python -m venv venv
venv\Scripts\activate
```

Once activated, you will see `(venv)` appear at the beginning of the command line.

If you want to exit the virtual environment at any time:

```bash
deactivate
```

## Step 4: Installing Streamlit and Dependencies

Inside the virtual environment, install the necessary Python packages:

```bash
pip install streamlit pandas altair matplotlib seaborn
```

## Step 5: Running the Streamlit Application

Still inside the `venv`:

```bash
streamlit run app.py
```

A web browser window should open automatically at:

```
http://localhost:8501
```

If it doesn't, manually open your browser and enter the address.

---

If USDA prefers internal hosting, this method allows complete local control similar to Hugging Face hosting.