nabhot/extreme-value-analysis

Extreme Value Analysis (EVA) Web Application

An interactive web application for conducting Extreme Value Analysis (EVA) on particle/inclusion sizes using the Gumbel distribution (4-quadrant method).

🚀 How to Run the Application

You can start both the backend and frontend services using the provided batch file or by running them manually in separate terminals.

Method 1: Automatic Startup (Windows)

Simply double-click the batch file in the root folder:

run_local_react_ui.bat

This script will:

1. 1.Initialize the Python virtual environment (.venv) if it doesn't exist.
2. 2.Install Python backend dependencies.
3. 3.Launch the FastAPI backend on http://localhost:8000.
4. 4.Install frontend npm dependencies.
5. 5.Launch the React dev server on http://localhost:5173.

Method 2: Manual Startup (All Platforms)

To run backend and frontend separately, open two terminal windows:

1. Start the FastAPI Backend

# Navigate to the backend directory
cd backend

# Create a virtual environment (if not already done)
python -m venv .venv

# Activate the virtual environment
#{
# Windows PowerShell:
.\.venv\Scripts\Activate.ps1
# Windows CMD:
.\.venv\Scripts\activate.bat
# Linux/macOS:
source .venv/bin/activate
#}
# Install requirements
pip install -r requirements.txt

# Start the backend server
uvicorn main:app --reload --port 8000

The API will be available at `http://127.0.0.1:8000` (docs at `http://127.0.0.1:8000/docs`).

2. Start the React Frontend

# Navigate to the frontend directory
cd frontend

# Install package dependencies
npm install

# Start Vite development server
npm run dev

The user interface will be available at `http://localhost:5173`.

📊 Features & Methodology

1. 1.Excel Data Import: Uploads Excel sheets containing numeric columns matching Length and Width (case-insensitive).
2. 2.Equivalent Diameter Calculation: Computes equivalent diameter for each particle/inclusion: $$X_i = \sqrt{\text{Length} \times \text{Width}}$$
3. 3.Gumbel Fitting (Linear Regression): Sorts equivalent diameters $Xi$ on the X-axis and plots them against Gumbel reduced variable $Gi$ on the Y-axis: $$Pi = \frac{i}{n + 1}$$ $$Gi = -\ln(-\ln(P_i))$$
4. 4.Extreme Value Prediction: Computes the return period $T$, target Gumbel value $G$, and predicted maximum equivalent diameter: $$X_{max} = \frac{G - \text{intercept}}{\text{slope}}$$
5. 5.Interactive Visualization: Generates high-quality charts showing measured data points, the regression line, and the predicted maximum inclusion diameter.

🌐 Free Hosting Options

Since the application is containerized using the provided Dockerfile, you can easily host it for free on several platforms.

Option A: Hugging Face Spaces (Recommended & 100% Free)

Hugging Face Spaces offers free Docker hosting that remains online and does not sleep as aggressively as other free tiers.

1. 1.Create a free account on Hugging Face.
2. 2.Create a new Space:
3. 3.Choose any name you like.
4. 4.Select Docker as the SDK.
5. 5.Select the Blank template.
6. 6.Choose Public or Private visibility.
7. 7.Once created, upload all the repository files (including the Dockerfile, backend, frontend, etc.) directly via Git or the web interface.
8. 8.The space will automatically read the metadata at the top of this README.md, build the container, and host the app.

Option B: Render (Free Web Service)

Render is a cloud hosting platform that can deploy directly from your GitHub repository.

1. 1.Create a free account on Render.
2. 2.Click New + and select Web Service.
3. 3.Connect your GitHub repository.
4. 4.Set the following configurations:
5. 5.Runtime: Docker
6. 6.Branch: main (or whichever branch you push to)
7. 7.Free Instance Type
8. 8.Render will automatically build the Dockerfile and deploy the application. (Note: Render free services will spin down/sleep after 15 minutes of inactivity. The first request after a sleep period can take ~50 seconds to spin back up).

Option C: Koyeb (Free Micro Instance)

Koyeb is a container-based developer platform that offers a free tier.

1. 1.Create a free account on Koyeb.
2. 2.Create a new service and connect your GitHub repository.
3. 3.Select Docker as the builder.
4. 4.Set the port to 8000 and deploy.