Mizzou-Student-Research-Team/Alt-v2-Seismometer-Network-Builder

User (Browser)
│
└── Streamlit Frontend (Hugging Face Space)
    │
    ├── Home.py
    │   └── Overview, instructions, troubleshooting
    │
    ├── 1_1️⃣_Step_1.py  (Earthquake Selection)
    │   ├── Queries USGS ComCat via libcomcat
    │   ├── Filters events by magnitude, date, and West Coast bounds
    │   └── Stores selected_eq in st.session_state
    │
    ├── 2_2️⃣_Step_2.py  (Nodal Network Generation)
    │   ├── Nodal Site Generation
    │   │     • Provide option to user to make any changes
    │   │     • Generate nodal network based on magnitude of the earthquake
    │
    ├── 3_3️⃣_Step_3.py  (Explore Results)
    │   ├── Depicts map with the results
    │   ├── Incorporates a data visualization
    │
    ├── 4_🤖_AI_Assistant.py
    │   ├── Uses RAG (Retrieval-Augmented Generation) model
    │   ├── Loads local knowledge/*.txt files 
    │   ├── Maintains conversation history in st.session_state
    │   └── Calls Groq LLM (OpenAI-compatible API)
    │
    ├── 5_🔍_Further_Analysis_and_Resources.py
    │   └── Provides GeoJSON downloads for nodal network and all cells
    │
    └── 6_📃_Credits_and_Policies.py
        └── Shows credits, terms, license, and citations


──────────────────────────────────────────────────────────────
Backend Components
──────────────────────────────────────────────────────────────
The backend of the Seismometer Network Builder is a coordinated set of
external data services and cloud storage that
support the Streamlit frontend. Each component is triggered in sequence
as the user progresses through the tool.

• Hugging Face Dataset Repository  
    Stores all technical, contextual, and social datasets used in Steps 2–3.

• USGS ComCat API  
    Triggered in Step 1 when the user searches for earthquakes.

---

## Repository Structure

---

# Technical Workflow

## Step 1 — Earthquake Selection (USGS ComCat)

**File:** `1_1️⃣_Step_1.py`

The tool queries the USGS ComCat API using `libcomcat.search` with filters for:

- Date range  
- Magnitude range (5.0–8.0)  
- West Coast bounding box  

Each event includes magnitude, depth, time, place, USGS URL, and epicenter geometry. The selected event is stored in:

This defines the epicenter, magnitude, and initial ROI.

---

## Step 2 — Nodal Network Generation

**File:** `2_2️⃣_Step_2.py`

This is the computational core of the tool.

### 2.1 ROI Definition (MMI Attenuation Model)

The tool uses the Atkinson, Worden & Wald (2014) Western North America MMI model to compute the radius where MMI = 5.0. The ROI is a square bounding box around the epicenter.

### 2.2 Allow user to make any changes
Users can make changes by adjusting the parameters or by drawing new shapes directly on the interactive map to define the unsuitable areas.

### 2.3 Greedy Spacing Algorithm

Magnitude‑based defaults:

| Magnitude | Target Nodes | Spacing |
|-----------|--------------|---------|
| 5.0–5.9 | 30 | 5 km |
| 6.0–6.9 | 70 | 7.5 km |
| 7.0–7.9 | 100 | 40 km |
| 8.0 | 150 | 40 km |

Users may override these values.

After this, the nodal network sites are stored in a geodataframe for analysis in the next step.

---

## Step 3 — Results

**File:** `3_3️⃣_Step_3.py`

### Map and Data Visualization Depicted
- Map shows the chosen nodal sites
- Data visualization is about the epicenter to seismometer site distances

---

## AI Assistant

**File:** `4_🤖_AI_Assistant.py`

- Uses Groq Llama‑3.1 via OpenAI‑compatible API  
- Loads local knowledge files  
- Maintains conversation history  
- Helps users understand the workflow and provides background information

---

## Downloads & Resources

**File:** `5_🔍_Further_Analysis_and_Resources.py`

Users can download:

- Nodal Network Sites (GeoJSON)  
- All Candidate Sites (GeoJSON)  

Also links to:

- Dataset repository  
- Project slides  

---

# Running the Tool Locally

### 1. Clone the repository

### 2. Install dependencies

### 3. Add secrets

Create `.streamlit/secrets.toml`:

- **groq_key** — Log into your Groq account → go to API Keys → create a new key → paste it here.

### 4. Run Streamlit

---

# Reusing This Codebase

This project was intentionally designed so that users can reuse the
components independently. You do not need to deploy the full Streamlit
app to benefit from the underlying logic.

Below are three recommended reuse pathways.


## 1. Reusing the Core Step 2 Workflow

The entire nodal network generation workflow lives in `2_2️⃣_Step_2.py` and can
be extracted into a standalone Python module.

You can reuse:

- the ROI computation using the MMI attenuation model
- the uniform grid generator (create_grid) that builds fixed‑size cells across the ROI
- the drawing‑tool exclusion logic, which merges user‑drawn polygons and marks intersecting cells as unsuitable
- the suitability filter that removes excluded cells
- the centroid extraction that produces a clean GeoDataFrame of candidate seismometer locations

### How to use it independently
1. Copy the relevant functions from this file into a standalone module (e.g., suitability_workflow.py).
2. Replace Streamlit inputs with function arguments (e.g., ROI bounds, cell size, drawn shapes).
3. Call the workflow from any environment, such as:
   - a Jupyter notebook
   - a batch processing script
   - an automated backend service
   - a geospatial analysis pipeline

This allows users to run the model **without** Streamlit, BigQuery, or ArcGIS.

## 2. Reusing Only the Data Results Workflow

If you would like to depict data insights but not in the Streamlit UI:

You can reuse:

- The interactive map created with `leafmap` and `folium`
- The histogram-based spatial distribution analysis visualization

### How to use it independently
1. Generate your own GeoDataFrames (from Python, R, ArcGIS Pro, etc.).
2. Compute distances between geospatial features using GeoPandas.
3. Generate interactive maps with `leafmap` and `folium`.
4. Create statistical visualizations and distance histograms using Plotly.
5. Export the outputs into notebooks, dashboards, standalone web apps, or GIS platforms.


## 3. Reusing the AI Assistant

The AI assistant is fully modular and lives in `4_🤖_AI_Assistant.py`.

You can reuse:

- The Groq API call wrapper
- The knowledge‑file retrieval system
- The conversation memory logic

### How to use it independently
1. Move the AI assistant code into a separate module (e.g., `assistant.py`).
2. Replace Streamlit chat UI with a tool of your choice such as:
   - a CLI interface  
   - a Slack bot  
   - a Teams bot  
   - an internal web app  

### Should you separate it into a Hugging Face model?
If you want the assistant to be reusable across multiple tools, yes —  
you can package the assistant logic in different ways such as:

- a **Hugging Face Model (API endpoint can be enabled)**  
- a **Python package**

This is optional but recommended if you want a unified assistant across projects.


## 4. Reusing the Remaining Code

The rest of the codebase is primarily:

- UI text  
- Page layout  
- Download buttons  
- Video embedding  
- Credits and policies  

These components are optional and can be removed or replaced without
affecting the core functionality.

---

# Contributing

We welcome contributions from users who want to improve the Seismometer Network Builder or adapt it for new use cases.

## How to Contribute
1. **Duplicate the repository**  
   Create your own copy of the project to work on.

2. **Create a feature branch** 
   `git checkout -b feature/my-improvement`

3. **Make your changes**  
- Add new features  
- Improve documentation  
- Fix bugs  
- Enhance performance  
- Add new datasets or workflows  

4. **Submit a pull request**  
Include a clear description of what you changed and why.

## Contribution Guidelines
- Keep code modular and consistent with existing structure.  
- Document new functions or workflows clearly.  
- Do NOT commit secrets or credentials. This poses a security risk. 
- If adding new datasets, include metadata and source information.  

We appreciate all contributions — whether small fixes or major enhancements!

--- 

# Limitations of Our Web Tool

While the tool is fully functional, here are some limitations to be aware of:

## 1. ROI Simplification
The Region of Interest is defined as a square bounding box based on MMI attenuation.  
This is intentionally simple but may not capture important details.

## 2. Raster Resolution
The workflow uses a 5.5 km grid to balance performance and spatial accuracy.  
Higher‑resolution grids are supported, but they may substantially increase processing time and memory usage.

## 3. AI Assistant Scope
The AI assistant uses local knowledge files and does not have access to the full codebase.  
It is designed for guidance, not for executing or modifying workflows.

## 4. Internet Connectivity
Several components require external APIs:
- USGS ComCat  
- IRIS FDSN  
- Overpass API  
- Hugging Face Datasets  

Offline use is limited unless datasets are cached locally.

--- 

# Acknowledgements

This project was developed in partnership with:

- USGS Research Geophysicists  
- MU Institute for Data Science & Informatics  
- BrightData  

And built upon:

- Streamlit multipage template by Dr. Qiusheng Wu  
- Open datasets from USGS, IRIS, FEMA, Esri, OSM, and others

---

# Glossary

- **HF:** Hugging Face
- **ROI:** Region of Interest
- **EDA:** Exploratory Data Analysis
- **OSM:** OpenStreetMap (a volunteer-run organization)
- **CLI:** Command Line Interface

--- 

**Note: This README documentation was created by Microsoft Copilot and edited by the team.**