README_space.md

# 📊 Seaborn & Matplotlib Visual Lab

Interactive **Streamlit** Space to explore **Seaborn** and **Matplotlib** side by side — from quick EDA plots to copy-ready code snippets you can reuse in notebooks.

This Space runs fully in the browser.  
No uploads are required: it uses **Seaborn’s built-in demo datasets** for safe, fast experimentation.

[![Streamlit](https://img.shields.io/badge/Powered%20by-Streamlit-FF4B4B)](https://streamlit.io/)
[![Seaborn](https://img.shields.io/badge/Seaborn-Statistical%20Visuals-0ea5e9.svg)](https://seaborn.pydata.org/)
[![Matplotlib](https://img.shields.io/badge/Matplotlib-Plot%20Engine-11557c.svg)](https://matplotlib.org/)
[![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg)](LICENSE)

---

## ✅ What you can do here

- Load classic **Seaborn demo datasets** (Tips, Penguins, Flights, Iris, Diamonds, Titanic, Car Crashes)
- Build **Seaborn plots** interactively (distribution, relationships, categories, heatmaps, pairplots)
- Recreate the same patterns using **Matplotlib** with lower-level control
- Compare **Seaborn vs Matplotlib** for the *same* idea on one screen
- Save figures into a **gallery** and download PNGs (or a ZIP archive)

Use it as a small **visual lab**: learn → tweak → copy the code → reuse in real projects.

---

## 🧭 How to use the Space

The app is organized into five main tabs:

### 1) Overview
High-level view of the active dataset:
- sample preview
- dtypes + missingness summary
- quick numeric distribution
- small correlation heatmap (subset of numeric features)

### 2) Seaborn builder
UI-driven Seaborn plotting:
- plot families: **Distribution, Relationship, Category, Matrix/Heatmap, Multi-variable**
- controls: columns, bins, KDE/ECDF, log-scale, hue grouping, top-K categories
- auto-updated **Python snippet** you can copy

### 3) Matplotlib builder
Low-level Matplotlib plotting:
- plot types: **Line, Scatter, Bar, Histogram, Box, Subplots overview**
- controls: axes, markers/size/alpha, horizontal vs vertical bars, density vs counts

### 4) Compare
Side-by-side mapping between high-level Seaborn and raw Matplotlib:
- **Distribution pattern:** histogram + KDE
- **Relationship pattern:** scatter plot

### 5) Gallery
Export hub:
- save plots into a session gallery
- download individual PNGs
- download a ZIP with all saved figures

---

## 📚 Datasets (built-in, no uploads)

All data lives inside the Space and comes from **Seaborn’s built-in catalog** — no external APIs and no personal data.

Available datasets:
- `tips`
- `penguins` (NaNs dropped)
- `flights`
- `iris`
- `diamonds` (sample)
- `titanic`
- `car_crashes`

Switch datasets from the sidebar and the plots update instantly.

---

## 📸 Preview

<p align="center">
  <img src="assets/seaborn-tips-total-bill-hist-sex.png" alt="Seaborn histogram: tips dataset" />
</p>

<p align="center">
  <img src="assets/matplotlib-iris-sepal-length-hist.png" alt="Matplotlib histogram: iris dataset" />
</p>

<p align="center">
  <img src="assets/compare-hist-kde-tips.png" alt="Compare: histogram + KDE" />
</p>

---

## 🧩 Tech stack

- **Python 3.11**
- **Streamlit** (app framework)
- **Seaborn** (high-level statistical plots)
- **Matplotlib** (core plotting engine)
- **NumPy / pandas** (data handling)

---

## 🖥 Run locally (same code as the Space)

### Windows (PowerShell)
```bash
git clone https://github.com/tarekmasryo/seaborn-matplotlib-visual-lab.git
cd seaborn-matplotlib-visual-lab

py -3.11 -m venv .venv
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1

python -m pip install -U pip
python -m pip install -r requirements.txt
python -m pip install -r requirements-dev.txt

python -m streamlit run app.py
```

### Linux / macOS
```bash
git clone https://github.com/tarekmasryo/seaborn-matplotlib-visual-lab.git
cd seaborn-matplotlib-visual-lab

python3 -m venv .venv
source .venv/bin/activate

python -m pip install -U pip
python -m pip install -r requirements.txt
python -m pip install -r requirements-dev.txt

python -m streamlit run app.py
```

---

## ✅ Development kit (quality checks)

This repo includes a lightweight quality kit:
- **ruff** for linting/formatting
- **pytest** for smoke tests
- **pre-commit** hooks
- optional **GitHub Actions** CI under `.github/workflows/`

Run locally:
```bash
python -m ruff check . --fix
python -m ruff format .
python -m pytest -q
pre-commit run --all-files
```

---

## 📜 License
Apache-2.0 — see [LICENSE](LICENSE).

---

## 👤 Author
Tarek Masryo