README.md

metadata

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, 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:

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.

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

Install Python using Homebrew:

brew install python

Creating Project Folders

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

python3 -m venv venv
source venv/bin/activate

To exit the virtual environment at any time:

deactivate

Step 4: Installing Streamlit and Dependencies

pip install streamlit pandas altair matplotlib seaborn

Step 5: Run the Streamlit application

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:

python --version

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

• Go to the official Python website
• 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:

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):

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:

deactivate

Step 4: Installing Streamlit and Dependencies

Inside the virtual environment, install the necessary Python packages:

pip install streamlit pandas altair matplotlib seaborn

Step 5: Running the Streamlit Application

Still inside the venv:

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.