sepehr/Analysis
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

initial commit

Browse Source
This commit is contained in:
sepehr
2026-01-11 22:56:02 +01:00
commit 6426ddd0ab
408 changed files with 95071 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

552
docs/CORRELATION_GUIDE.md Normal file
View File

@@ -0,0 +1,552 @@
# Guide Complet de la Corrélation
📊 **Comprendre et maîtriser l'analyse de corrélation** pour identifier les relations entre variables et construire des modèles robustes.
---
## Table des Matières
1. [Qu'est-ce que la Corrélation ?](#quest-ce-que-la-corrélation)
2. [Les Trois Méthodes](#les-trois-méthodes)
3. [Interpréter la Matrice](#interpréter-la-matrice)
4. [Multicolinéarité](#multicolinéarité)
5. [P-Values et Significativité](#p-values-et-significativité)
6. [Bonnes Pratiques](#bonnes-pratiques)
7. [Exemples Concrets](#exemples-concrets)
---
## Qu'est-ce que la Corrélation ?
### Définition
La **corrélation** mesure la **force** et la **direction** de la relation linéaire entre deux variables quantitatives.
### Coefficient de Corrélation
Le coefficient de corrélation **r** varie entre **-1 et +1** :
```
-1 ←----------|----------|----------|----------→ +1
négatif positif
fort fort
```
### Interprétation Générale
| Valeur r | Force | Direction | Signification |
|----------|-------|-----------|---------------|
| **0.9 à 1.0** | Très forte | Positive | X↑ ⇒ Y↑ fortement |
| **0.7 à 0.9** | Forte | Positive | X↑ ⇒ Y↑ |
| **0.5 à 0.7** | Modérée | Positive | X↑ ⇒ Y↑ modérément |
| **0.3 à 0.5** | Faible | Positive | X↑ ⇒ Y↑ légèrement |
| **0.0 à 0.3** | Très faible | Positive | Relation quasi nulle |
| **0.0** | Aucune | - | Indépendance linéaire |
| **-0.3 à 0.0** | Très faible | Négative | X↑ ⇒ Y↓ légèrement |
| **-0.5 à -0.3** | Faible | Négative | X↑ ⇒ Y↓ |
| **-0.7 à -0.5** | Modérée | Négative | X↑ ⇒ Y↓ modérément |
| **-0.9 à -0.7** | Forte | Négative | X↑ ⇒ Y↓ |
| **-1.0 à -0.9** | Très forte | Négative | X↑ ⇒ Y↓ fortement |
### Exemples Visuels
#### Corrélation Positive Forte (r = 0.95)
```
┌─────┐
│ Y │ •
│ │ •
│ │ •
│ │ •
│ │•
└─────┴─────→ X
```
**Exemple** : Taille vs Poids (plus grand = plus lourd)
#### Corrélation Négative Forte (r = -0.90)
```
┌─────┐
│ Y │•
│ │ •
│ │ •
│ │ •
│ │ •
└─────┴─────→ X
```
**Exemple** : Vitesse vs Temps (plus vite = moins de temps)
#### Corrélation Nulle (r = 0.02)
```
┌─────┐
│ Y │ • • •
│ │• •
│ │ • •
│ │ • •
│ │• •
└─────┴─────→ X
```
**Exemple** : Taille vs Note en mathématiques
---
## Les Trois Méthodes
L'application propose **3 méthodes** de calcul de corrélation :
### 1. Pearson (Défaut)
**Quand l'utiliser ?**
- ✅ Données **normalement distribuées**
- ✅ Relation **linéaire**
- ✅ Variables **continues**
**Hypothèses** :
- Distribution normale (pas trop asymétrique)
- Pas d'outliers extrêmes
- Relation linéaire
**Formule** :
```
Σ[(Xi - X̄)(Yi - Ȳ)]
r = ----------------------------
√[Σ(Xi - X̄)²] √[Σ(Yi - Ȳ)²]
```
**Exemple** :
```python
# Température vs Vent (relation linéaire, normale)
# Corrélation de Pearson : r = 0.85 (forte positive)
```
---
### 2. Spearman
**Quand l'utiliser ?**
- ✅ Données **non-paramétriques** (pas normales)
- ✅ Relation **monotone** (pas forcément linéaire)
- ✅ Présence d'**outliers**
- ✅ Variables **ordinales** (rangs)
**Hypothèses** :
- Relation monotone (toujours dans le même sens)
- Moins sensible aux outliers
**Principe** :
Convertit les données en **rangs** avant calcul.
**Exemple** :
```python
# Revenu vs Satisfaction (relation monotone mais non linéaire)
# Revenu: [1000, 2000, 5000, 10000, 50000]
# Rangs: [1, 2, 3, 4, 5]
# Corrélation de Spearman : r = 0.90
```
**Différence Pearson vs Spearman** :
```
Pearson (linéaire) :
•
•
•
•
•
Spearman (monotone) :
•
•
•
•
•
```
---
### 3. Kendall (Tau)
**Quand l'utiliser ?**
- ✅ **Petits échantillons** (n < 30)
- ✅ Beaucoup de **valeurs identiques** (ex-aequo)
- ✅ Données **ordinales**
**Hypothèses** :
- Mesure la concordance des paires
**Principe** :
Compte les paires **concordantes** vs **discordantes**.
**Exemple** :
```python
# Classement vs Préférence (10 étudiants)
# Kendall Tau = 0.67 (modéré)
```
---
## Interpréter la Matrice
### Structure de la Heatmap
```
Var1 Var2 Var3 Var4
┌───────┬───────┬───────┬───────┐
Var1 │ 1.00 │ 0.85 │ -0.30 │ 0.15 │
├───────┼───────┼───────┼───────┤
Var2 │ 0.85 │ 1.00 │ -0.20 │ 0.45 │
├───────┼───────┼───────┼───────┤
Var3 │ -0.30 │ -0.20 │ 1.00 │ 0.92 │ ← Multicolinéarité
├───────┼───────┼───────┼───────┤
Var4 │ 0.15 │ 0.45 │ 0.92 │ 1.00 │
└───────┴───────┴───────┴───────┘
```
### Lecture de la Heatmap
#### Couleurs
- **Rouge foncé** (r > 0.7) : Forte corrélation positive
- **Rouge clair** (0.3 < r < 0.7) : Corrélation modérée/positive
- **Gris/Blanc** (|r| < 0.3) : Corrélation faible/nulle
- **Bleu clair** (-0.7 < r < -0.3) : Corrélation modérée/négative
- **Bleu foncé** (r < -0.7) : Forte corrélation négative
#### Bordure Rouge ⚠️
- Indique une **multicolinéarité problématique** (|r| ≥ 0.7)
- Entre deux **prédicteurs** (variables X)
- À éviter dans la régression
### Diagonale
- Toujours égale à **1.00** (corrélation de la variable avec elle-même)
- Non pertinente pour l'analyse
---
## Multicolinéarité
### Définition
La **multicolinéarité** se produit lorsque deux ou plusieurs prédicteurs sont **fortement corrélés** entre eux (|r| ≥ 0.7).
### Pourquoi c'est Problématique ?
❌ **Effets sur la Régression** :
- Coefficients **instables** (varient beaucoup)
- **p-values** peu fiables
- Difficulté d'interpréter l'effet isolé de chaque variable
- **R²** artificiellement élevé
### Exemple de Multicolinéarité
```python
# Dataset : Prix immobiliers
# Variables :
# - Surface_m²
# - Surface_pieds² (même variable, unité différente)
# - Prix
# Corrélation Surface_m² vs Surface_pieds² : r = 1.0
# ⚠️ BORDURE ROUGE sur la heatmap
# Problème dans la régression :
# Prix = 50000 + 1000*Surface_m² - 200*Surface_pieds²
# ^^^^^ coefficient positif ^^^^^^^^ coefficient négatif ???
# absurde ! (les deux expliquent la même chose)
```
### Détection
Dans l'application :
1. **Ouvrez** la matrice de corrélation
2. **Recherchez** les bordures rouges entre prédicteurs
3. **Notez** les variables concernées
### Solution
**Option 1 : Supprimer une variable**
```python
# Avant : Surface_m² (r=1.0) vs Surface_pieds²
# Solution : Garder Surface_m², supprimer Surface_pieds²
```
**Option 2 : Combiner les variables**
```python
# Avant : Note_Maths, Note_Physique, Note_Chimie (toutes corrélées)
# Solution : Créer "Note_Scientifique" = moyenne des trois
```
**Option 3 : Analyse de corrélation partielle**
Utiliser des techniques avancées (hors scope du guide)
### Checklist Avant Régression
Avant de lancer votre régression, vérifiez :
✅ **Aucune bordure rouge** entre les prédicteurs potentiels
✅ **Si bordure rouge** : choisissez la variable la plus corrélée avec la cible
✅ **Documentez** votre choix de retrait de variable
---
## P-Values et Significativité
### Qu'est-ce que la P-Value ?
La **p-value** mesure la **probabilité** que la corrélation observée soit due au hasard.
- **p-value < 0.05** : Corrélation **statistiquement significative** (fiable)
- **p-value ≥ 0.05** : Corrélation **non significative** (pourrait être due au hasard)
### Interprétation
| Corrélation (r) | P-Value | Interprétation |
|-----------------|---------|----------------|
| 0.85 | p < 0.001 | ✅ Forte et significative |
| 0.60 | p = 0.040 | ✅ Modérée et significative |
| 0.75 | p = 0.080 | ⚠️ Forte mais NON significative (échantillon trop petit) |
| 0.30 | p = 0.200 | ❌ Faible et non significative |
### Impact de la Taille d'Échantillon
```
Pour r = 0.30 :
n = 10 → p = 0.40 (non significatif)
n = 50 → p = 0.03 (significatif)
n = 100 → p = 0.002 (très significatif)
```
**Règle** : Plus l'échantillon est grand, plus les petites corrélations deviennent significatives.
### Filtre "Significatif Seulement"
Dans l'application :
- **Cochez** "Significatif seulement (p < 0.05)"
- La heatmap n'affiche que les corrélations **statistiquement fiables**
- Utile pour filtrer le bruit
---
## Bonnes Pratiques
### 1. Vérifier les Hypothèses
**Pour Pearson** :
```python
# Test de normalité (Shapiro-Wilk)
from scipy.stats import shapiro
stat, p = shapiro(data['variable'])
if p > 0.05:
print("Distribution normale → Pearson OK")
else:
print("Distribution non normale → Utiliser Spearman")
```
**Vérification visuelle** :
```python
import matplotlib.pyplot as plt
plt.hist(data['variable'])
plt.show()
# Forme de cloche = normale
```
### 2. Traiter les Outliers
Les outliers faussent **fortement** la corrélation Pearson :
```python
# Sans outlier : r = 0.95
X = [1, 2, 3, 4, 5]
Y = [2, 4, 6, 8, 10]
# Avec outlier : r = 0.40
X = [1, 2, 3, 4, 100] # 100 est outlier
Y = [2, 4, 6, 8, 10]
# Solution : utiliser Spearman (robuste aux outliers)
# Ou supprimer l'outlier
```
### 3. Corrélation ≠ Causalité
⚠️ **Attention** : Une corrélation forte n'implique PAS que X cause Y.
**Exemples classiques** :
- 🍦 Ventes de glace vs 🦈 Attaques de requins
- Corrélation : r = 0.90
- Cause commune : 🌞 Été (chaleur)
- Solution : Pas de causalité directe
- ☕ Café vs 💰 Revenu
- Corrélation : r = 0.75
- Explication : Les riches boivent plus de café (ou l'inverse ?)
- Nécessite une expérience contrôlée
### 4. Corrélation de Spearman pour les Relations Non-Linéaires
```python
# Relation exponentielle
X = [1, 2, 3, 4, 5]
Y = [1, 4, 9, 16, 25] # Y = X²
# Pearson : r = 0.97 (mais PAS linéaire !)
# Spearman : r = 1.00 (monotone parfaite)
```
### 5. Matrice de Corrélation Avant Régression
**Workflow recommandé** :
```
1. Charger les données
↓
2. Matrice de corrélation
↓
3. Identifier les variables fortement corrélées avec la cible (|r| > 0.5)
↓
4. Repérer la multicolinéarité entre prédicteurs (bordure rouge)
↓
5. Sélectionner les prédicteurs finaux (pas de multicolinéarité)
↓
6. Régression
```
---
## Exemples Concrets
### Exemple 1 : Immobilier
**Dataset** : Prix, Surface, Chambres, Jardin, Garage, Distance_Centre
**Matrice de corrélation** :
```
Prix Surface Chambres Jardin Garage Distance
Prix 1.00 0.85 0.65 0.70 0.55 -0.75
Surface 0.85 1.00 0.72 0.60 0.50 -0.40
Chambres 0.65 0.72 1.00 0.45 0.35 -0.25
Jardin 0.70 0.60 0.45 1.00 0.30 -0.50
Garage 0.55 0.50 0.35 0.30 1.00 -0.20
Distance -0.75 -0.40 -0.25 -0.50 -0.20 1.00
```
**Analyse** :
1. **Variables corrélées avec le Prix** :
- Surface : r = 0.85 ✅ (très forte)
- Distance : r = -0.75 ✅ (forte négative)
- Jardin : r = 0.70 ✅ (forte)
- Chambres : r = 0.65 ✅ (modérée)
2. **Multicolinéarité** :
- Surface vs Chambres : r = 0.72 ⚠️ (proche du seuil)
- Si r > 0.7 : choisir une seule variable
3. **Sélection finale** :
- X = Surface, Distance, Jardin
- Éviter Chambres (multicolinéarité avec Surface)
---
### Exemple 2 : Santé
**Dataset** : IMC, Tension, Cholestérol, Âge, Sport, Calories
**Matrice (Spearman)** :
```
IMC Tension Cholestérol Âge Sport Calories
IMC 1.00 0.55 0.48 0.30 -0.60 0.70
Tension 0.55 1.00 0.65 0.45 -0.40 0.50
Cholestérol 0.48 0.65 1.00 0.60 -0.35 0.45
Âge 0.30 0.45 0.60 1.00 -0.25 0.20
Sport -0.60 -0.40 -0.35 -0.25 1.00 -0.50
Calories 0.70 0.50 0.45 0.20 -0.50 1.00
```
**Analyse** :
- **Prédicteurs du Tension** : Cholestérol (0.65), IMC (0.55)
- **Multicolinéarité** : IMC vs Calories (0.70) ⚠️
- **Action** : Garder IMC (plus corrélé avec Tension), exclure Calories
---
### Exemple 3 : Marketing
**Dataset** : Ventes, Budget_TV, Budget_Radio, Budget_Online, Prix, Concurrence
**Matrice** :
```
Ventes Budget_TV Budget_Radio Budget_Online Prix Concurrence
Ventes 1.00 0.80 0.45 0.72 -0.60 -0.40
Budget_TV 0.80 1.00 0.30 0.55 -0.20 -0.10
Budget_Radio 0.45 0.30 1.00 0.35 -0.15 -0.05
Budget_Online 0.72 0.55 0.35 1.00 -0.25 -0.15
Prix -0.60 -0.20 -0.15 -0.25 1.00 0.20
Concurrence -0.40 -0.10 -0.05 -0.15 0.20 1.00
```
**Décisions** :
1. **Meilleur canal** : TV (r = 0.80)
2. **Deuxième** : Online (r = 0.72)
3. **Radio** : Moins efficace (r = 0.45)
4. **Pas de multicolinéarité** sévère entre canaux
5. **Sélection** : Budget_TV, Budget_Online, Prix, Concurrence
---
## 📊 Fonctionnalités de l'Application
### Contrôles
1. **Sélection de la méthode**
- Menu déroulant : Pearson / Spearman / Kendall
- Défaut : Pearson
2. **Seuil minimum**
- Filtre les corrélations faibles
- Exemple : 0.5 n'affiche que |r| ≥ 0.5
3. **Filtre de significativité**
- Cochez "Significatif seulement"
- Garantit p < 0.05
4. **Export CSV**
- Téléchargez la matrice complète
- Inclut corrélations et p-values
### Composants Visuels
#### Cartes de Résumé
- **Corrélations les plus fortes** : Top 5 par |r|
- **Corrélations les plus faibles** : Bottom 5 non nulles
#### Tooltip (Survol)
Cliquez sur une case pour voir :
- Noms des variables
- Coefficient de corrélation
- P-value
- Significativité (✅/❌)
- Interprétation (Fort/Moyen/Faible)
---
## 🎯 Checklist d'Analyse
Avant de passer à la régression :
- [ ] **Méthode choisie** selon la distribution des données
- [ ] **Corrélations avec la cible** identifiées (|r| > 0.5 souhaité)
- [ ] **Multicolinéarité** vérifiée (pas de bordure rouge entre prédicteurs)
- [ ] **P-values** significatives (p < 0.05)
- [ ] **Outliers** traités (si Pearson)
- [ ] **Variables sélectionnées** documentées
- [ ] **Résultats exportés** pour référence future
---
**Version** : 1.0
**Projet** : Application d'Analyse de Données
**Auteur** : Documentation Utilisateur
🔗 **Voir aussi** : [Guide Régression](REGRESSION_GUIDE.md) | [Guide Outliers](OUTLIER_GUIDE.md)

438
docs/LOCAL_SETUP_GUIDE.md Normal file
View File

@@ -0,0 +1,438 @@
# Local Development Setup Guide
This guide provides step-by-step instructions for setting up and running the Data Analysis Platform on your local machine.
---
## Table of Contents
1. [Prerequisites Installation](#1-prerequisites-installation)
2. [Backend Setup](#2-backend-setup)
3. [Frontend Setup](#3-frontend-setup)
4. [Running Both Services](#4-running-both-services)
5. [Verification](#5-verification)
6. [Common Issues and Solutions](#6-common-issues-and-solutions)
7. [Development Tips](#7-development-tips)
---
## 1. Prerequisites Installation
### Verify Your Installation
Before starting, verify you have the required tools installed:
```bash
# Check Python version (must be 3.12+)
python3.12 --version
# Check Node.js version (must be 20+)
node --version
# Check npm (comes with Node.js)
npm --version
# Check UV (Python package manager)
uv --version
```
### Install Missing Prerequisites
#### Python 3.12
**macOS (using Homebrew):**
```bash
brew install python@3.12
```
**Ubuntu/Debian:**
```bash
sudo apt update
sudo apt install python3.12 python3.12-venv
```
**Windows:**
Download from [python.org](https://www.python.org/downloads/)
#### Node.js 20+
**macOS (using Homebrew):**
```bash
brew install node
```
**Ubuntu/Debian:**
```bash
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
```
**Windows:**
Download from [nodejs.org](https://nodejs.org/)
#### UV (Python Package Manager)
```bash
pip install uv
# or
pipx install uv
```
---
## 2. Backend Setup
### Step 1: Navigate to Backend Directory
```bash
cd backend
```
### Step 2: Create Virtual Environment
A virtual environment isolates your project dependencies:
```bash
# Create virtual environment
python3.12 -m venv .venv
# Activate on macOS/Linux
source .venv/bin/activate
# Activate on Windows
.venv\Scripts\activate
```
You should see `(.venv)` appear in your terminal prompt.
### Step 3: Install Dependencies with UV
UV is a fast Python package installer that resolves dependencies quickly:
```bash
uv sync
```
This reads `pyproject.toml` and `uv.lock` to install exact versions of all dependencies.
### Step 4: Verify Installation
```bash
python -c "import fastapi; import pandas; import pyarrow; print('All dependencies installed!')"
```
### Step 5: Start the Backend Server
```bash
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```
**Command explained:**
- `uvicorn` - ASGI server for FastAPI
- `main:app` - Points to the FastAPI app instance in `main.py`
- `--reload` - Auto-reload on code changes (development mode)
- `--host 0.0.0.0` - Listen on all network interfaces
- `--port 8000` - Use port 8000
You should see output like:
```
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO: Started reloader process [12345] using WatchFiles
INFO: Started server process [12346]
INFO: Waiting for application startup.
INFO: Application startup complete.
```
### Step 6: Access Backend Services
Open your browser and navigate to:
- **API Root:** http://localhost:8000
- **Swagger UI (Interactive API Docs):** http://localhost:8000/docs
- **ReDoc (Alternative API Docs):** http://localhost:8000/redoc
---
## 3. Frontend Setup
### Step 1: Open New Terminal
Keep the backend running in its terminal. Open a **new terminal** for the frontend.
### Step 2: Navigate to Frontend Directory
```bash
cd frontend
```
### Step 3: Install Dependencies
```bash
npm install
```
This downloads all packages listed in `package.json` and `package-lock.json`.
Expected output includes packages like:
- `next` (16.1.1)
- `react` (19.2.3)
- `typescript` (latest)
- `tailwindcss` (4+)
- `apache-arrow` (21+)
### Step 4: Configure Environment (Optional)
Check if `.env.local` exists:
```bash
ls -la .env.local
```
If not present, create it from the example (if available):
```bash
cp .env.local.example .env.local
```
Edit `.env.local` to configure environment-specific settings like API endpoints.
### Step 5: Start the Frontend Development Server
```bash
npm run dev
```
You should see output like:
```
▲ Next.js 16.1.1
- Local: http://localhost:3000
- Network: http://192.168.1.X:3000
✓ Ready in 2.3s
```
### Step 6: Access Frontend Application
Open your browser and navigate to:
**Frontend App:** http://localhost:3000
---
## 4. Running Both Services
For full-stack development, run both services simultaneously.
### Option 1: Two Terminals (Recommended for Development)
**Terminal 1 - Backend:**
```bash
cd backend
source .venv/bin/activate # or .venv\Scripts\activate on Windows
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```
**Terminal 2 - Frontend:**
```bash
cd frontend
npm run dev
```
### Option 2: Background Processes
**Backend:**
```bash
cd backend
source .venv/bin/activate
uvicorn main:app --reload --host 0.0.0.0 --port 8000 > ../backend.log 2>&1 &
```
**Frontend:**
```bash
cd frontend
npm run dev > ../frontend.log 2>&1 &
```
View logs:
```bash
tail -f backend.log
tail -f frontend.log
```
---
## 5. Verification
### Test Backend Health
```bash
curl http://localhost:8000/docs
```
Or open http://localhost:8000/docs in your browser.
### Test Frontend
Open http://localhost:3000 in your browser.
### Check API Connectivity
From the frontend, you should be able to make requests to the backend at `http://localhost:8000`.
---
## 6. Common Issues and Solutions
### Port Already in Use
**Error:** `Address already in use`
**Solution:**
```bash
# Find process using port 8000 (backend)
lsof -i :8000
# or
netstat -tlnp | grep :8000
# Kill the process
kill -9 <PID>
# Or use a different port
uvicorn main:app --reload --port 8001
```
### Virtual Environment Issues
**Error:** Python command not found or wrong Python version
**Solution:**
```bash
# Deactivate current environment
deactivate
# Remove and recreate virtual environment
rm -rf .venv
python3.12 -m venv .venv
source .venv/bin/activate
uv sync
```
### Module Import Errors
**Error:** `ModuleNotFoundError: No module named 'fastapi'`
**Solution:**
```bash
# Ensure virtual environment is activated
source .venv/bin/activate
# Reinstall dependencies
uv sync
```
### Frontend Build Errors
**Error:** `Cannot find module 'X'`
**Solution:**
```bash
# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install
```
### CORS Errors (Frontend Cannot Access Backend)
**Error:** Browser console shows CORS policy errors
**Solution:**
Ensure the backend has CORS middleware configured. Check `backend/main.py` for:
```python
from fastapi.middleware.cors import CORSMiddleware
app.add_middleware(
CORSMiddleware,
allow_origins=["http://localhost:3000"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
```
---
## 7. Development Tips
### Hot Reload
- **Backend:** UVicorn's `--reload` flag automatically restarts the server when Python files change
- **Frontend:** Next.js dev server automatically refreshes the browser when files change
### Useful Commands
**Backend:**
```bash
# Run tests
pytest
# Run with verbose output
uvicorn main:app --reload --log-level debug
```
**Frontend:**
```bash
# Run tests (when configured)
npm test
# Build for production
npm run build
# Run production build
npm start
# Lint code
npm run lint
```
### IDE Recommendations
- **VS Code** with extensions:
- Python (Microsoft)
- Pylance
- ESLint
- Tailwind CSS IntelliSense
- Thunder Client (for API testing)
### Debugging
**Backend:** Use VS Code's debugger with launch configuration:
```json
{
"name": "Python: FastAPI",
"type": "debugpy",
"request": "launch",
"module": "uvicorn",
"args": ["main:app", "--reload", "--host", "0.0.0.0", "--port", "8000"],
"cwd": "${workspaceFolder}/backend"
}
```
**Frontend:** Use Chrome DevTools or React DevTools browser extension.
---
## Next Steps
Once both services are running:
1. Explore the API documentation at http://localhost:8000/docs
2. Interact with the frontend at http://localhost:3000
3. Review the project context at `_bmad-output/project-context.md`
4. Check planning artifacts in `_bmad-output/planning-artifacts/`
For Docker deployment instructions, see the main README.md (coming soon).
---
**Last Updated:** 2026-01-11

916
docs/OUTLIER_GUIDE.md Normal file
View File

@@ -0,0 +1,916 @@
# Guide Complet des Outliers (Valeurs Aberrantes)
🔍 **Identifier, comprendre et gérer les outliers** pour garantir la qualité de vos analyses statistiques.
---
## Table des Matières
1. [Qu'est-ce qu'un Outlier ?](#quest-ce-quun-outlier)
2. [Types d'Outliers](#types-doutliers)
3. [Méthodes de Détection](#méthodes-de-détection)
4. [Indicateurs Visuels](#indicateurs-visuels)
5. [Processus de Gestion](#processus-de-gestion)
6. [Impact sur les Analyses](#impact-sur-les-analyses)
7. [Bonnes Pratiques](#bonnes-pratiques)
8. [Exemples Concrets](#exemples-concrets)
---
## Qu'est-ce qu'un Outlier ?
### Définition
Un **outlier** (valeur aberrante) est une observation qui s'écarte **significativement** du reste des données.
### Caractéristiques
```
Données normales :
┌─┐
┌─┤ ├─┐ ← Distribution normale
│ │ │ │
└─┤ ├─┘
└─┘
Avec outliers :
┌─┐
┌─┤ ├─┐
│ │ │ │ ● ← Outlier élevé
└─┤ ├─┘ ●
└─┘ ● ← Outlier faible
```
### Pourquoi les Outliers Sont-Ils Importants ?
⚠️ **Ils peuvent fausser vos résultats** :
```python
# Moyenne SANS outlier
[10, 12, 11, 13, 12] → Moyenne = 11.6
# Moyenne AVEC outlier
[10, 12, 11, 13, 12, 100] → Moyenne = 26.3
# Impact : La moyenne est plus que doublée !
# Solution : Utiliser la médiane (robuste aux outliers)
```
---
## Types d'Outliers
L'application détecte **2 types** d'outliers :
### 1. Outliers Univariés 🔴
**Définition** : Valeur extrême dans **une seule variable**.
**Détection** : Méthode **IQR** (Interquartile Range)
**Exemple** :
```python
# Surface des appartements (m²)
[45, 50, 55, 60, 65, 70, 75, 500] # 500 est outlier
# Calcul :
Q1 = 52.5
Q3 = 71.25
IQR = Q3 - Q1 = 18.75
# Limite supérieure
Upper = Q3 + 1.5×IQR = 71.25 + 1.5×18.75 = 99.375
# 500 > 99.375 → OUTLIER 🔴
```
**Indicateur visuel** : **Cercle rouge** sur la valeur dans la table
---
### 2. Outliers Multivariés 🟣
**Définition** : Combinaison **inhabituelle** de plusieurs variables.
**Détection** : Algorithme **Isolation Forest**
**Exemple** :
```python
# Client : Âge=18, Revenu=100000€, Historique=0
# Individuellement :
# - Âge 18 : Normal
# - Revenu 100000€ : Normal
# - Historique 0 : Normal
# Mais COMBINÉ :
# → Jeune avec très haut revenu et aucun historique
# → SUSPECT ! (fraude potentielle, erreur de saisie, etc.)
# → OUTLIER MULTIVARIÉ 🟣
```
**Indicateur visuel** : **Cercle violet** sur la ligne dans la table
---
## Méthodes de Détection
### Méthode 1 : IQR (Interquartile Range)
#### Principe
L'IQR mesure la **dispersion centrale** des données (50% central).
```
┌────┬──────┬──────┬──────┬────┐
Min Q1 Médiane Q3 Max
└─────┬─────┘
IQR
```
#### Formules
```python
Q1 = 25ème percentile
Q3 = 75ème percentile
IQR = Q3 - Q1
Limite inférieure = Q1 - 1.5 × IQR
Limite supérieure = Q3 + 1.5 × IQR
# Outlier si :
valeur < Limite inférieure
OU
valeur > Limite supérieure
```
#### Exemple Pas à Pas
```python
# Données : Prix immobiliers
Prix = [150k, 180k, 200k, 220k, 250k, 280k, 300k, 1500k]
# Étape 1 : Trier
[150, 180, 200, 220, 250, 280, 300, 1500]
# Étape 2 : Calculer Q1 et Q3
Q1 = 190 (moyenne de 180 et 200)
Q3 = 290 (moyenne de 280 et 300)
# Étape 3 : Calculer IQR
IQR = 290 - 190 = 100
# Étape 4 : Calculer les limites
Limite_inf = 190 - 1.5×100 = 40
Limite_sup = 290 + 1.5×100 = 440
# Étape 5 : Identifier les outliers
150k > 40 ✅ Normal
180k > 40 ✅ Normal
...
300k < 440 ✅ Normal
1500k > 440 ❌ OUTLIER 🔴
```
#### Avantages et Limites
✅ **Avantages** :
- Simple à comprendre
- Robuste aux outliers (utilise des rangs)
- Fonctionne avec des données non normales
❌ **Limites** :
- Ne détecte que les extrêmes univariés
- Peut manquer des outliers multivariés
- Seuil 1.5 arbitraire (peut être ajusté)
---
### Méthode 2 : Isolation Forest
#### Principe
L'algorithme **isole** les observations en créant des partitions aléatoires. Les outliers sont **plus faciles à isoler** (moins de partitions nécessaires).
```
Forêt aléatoire d'arbres de décision :
- Chaque arbre partitionne les données
- Les outliers ont des chemins plus courts
- Score d'anomalie basé sur la longueur moyenne des chemins
```
#### Algorithme
```python
from sklearn.ensemble import IsolationForest
# 1. Entraîner le modèle
model = IsolationForest(
contamination='auto', # Détection automatique du seuil
random_state=42
)
# 2. Prédire
predictions = model.fit_predict(data_multivariée)
# Résultats :
# 1 → Normal
# -1 → Outlier 🟣
```
#### Exemple Visuel
```
Espace 2D (Âge, Revenu) :
Revenu
│
│ •
│ • •
│ • •
│ • ● • ← ● = Outlier multivarié
│ • • • (combinaison rare)
│• •
└──────────────→ Âge
```
#### Avantages et Limites
✅ **Avantages** :
- Détecte les outliers **multivariés**
- Ne nécessite pas de distribution normale
- Fonctionne avec des données de haute dimension
❌ **Limites** :
- Plus complexe à interpréter
- Résultats non déterministes (aléatoire)
- Peut varier selon le paramètre `contamination`
---
### Comparaison des Méthodes
| Critère | IQR | Isolation Forest |
|---------|-----|------------------|
| **Type** | Univarié | Multivarié |
| **Détection** | Valeurs extrêmes | Combinaisons rares |
| **Complexité** | Simple | Complexe |
| **Interprétabilité** | Élevée | Faible |
| **Robustesse** | Moyenne | Élevée |
| **Utilisation** | Première analyse | Analyse approfondie |
---
## Indicateurs Visuels
### Dans l'Application
#### 🔴 Cercle Rouge (Outlier Univarié)
**Affichage** : Sur la **cellule** spécifique
**Exemple** :
```
┌─────────────┬─────────────┬─────────────┐
│ Surface │ Prix │ Chambres │
├─────────────┼─────────────┼─────────────┤
│ 60 │ 250000 │ 3 │
│ 75 │ 300000 │ 4 │
│ 500 🔴 │ 350000 │ 5 │ ← Outlier sur Surface
│ 55 │ 280000 │ 3 │
└─────────────┴─────────────┴─────────────┘
```
**Information au survol** :
```
Column 'Surface' value 500 is outside IQR bounds [32.5, 115.5]
```
---
#### 🟣 Cercle Violet (Outlier Multivarié)
**Affichage** : Sur toute la **ligne**
**Exemple** :
```
┌─────────────┬─────────────┬─────────────┐
│ Âge │ Revenu │ Historique │
├─────────────┼─────────────┼─────────────┤
│ 35 │ 3000 │ 12 │
│ 42 │ 4500 │ 8 │
│ 18 🟣 │ 100000 │ 0 🟣 │ ← Outlier multivarié
│ 28 │ 2500 │ 5 │
└─────────────┴─────────────┴─────────────┘
```
**Information au survol** :
```
Multivariate anomaly detected by Isolation Forest
```
---
#### 🔴🟣 Les Deux (Outlier Univarié + Multivarié)
**Exemple** :
```
┌─────────────┬─────────────┬─────────────┐
│ Surface │ Prix │ Chambres │
├─────────────┼─────────────┼─────────────┤
│ 500 🔴🟣 │ 5000000 🔴 │ 10 🟣 │
└─────────────┴─────────────┴─────────────┘
```
**Interprétation** :
- 🔴 Surface et Prix sont des valeurs extrêmes
- 🟣 La combinaison Surface+Prix+Chambres est anormale
---
## Processus de Gestion
### Workflow Recommandé
```
1. Détection automatique
├─ IQR (univarié)
└─ Isolation Forest (multivarié)
2. Investigation manuelle
├─ Survoler les indicateurs colorés
├─ Lire les raisons détaillées
└─ Vérifier la source de données
3. Décision
├─ Conserver (valeurs légitimes)
├─ Corriger (erreurs de saisie)
└─ Exclure (vraies anomalies)
4. Ré-analyse
├─ Réexécuter la détection
├─ Vérifier l'impact sur les résultats
└─ Documenter les décisions
```
---
### Étape 1 : Identification
**Dans l'application** :
1. Importez vos données
2. Les outliers sont automatiquement détectés
3. Repérez les cercles 🔴 et 🟣
**Règle de priorité** :
```
🔴 Univarié → Vérifier en premier (simple)
🟣 Multivarié → Vérifier ensuite (complexe)
```
---
### Étape 2 : Investigation
#### Questions à se poser
**1. Est-ce une erreur de saisie ?**
```python
# Exemple : Âge = 250
# → Probablement une erreur (tapez 25 au lieu de 250)
# → Vérifier la source de données
# → Corriger si possible
```
**2. Est-ce une valeur légitime ?**
```python
# Exemple : Revenu = 1000000€ pour un CEO
# → Valeur extrême mais réelle
# → CONSERVER (pas d'erreur)
# → Vérifier l'impact sur l'analyse
```
**3. Est-ce un événement rare ?**
```python
# Exemple : Pic de ventes le Black Friday
# → Valeur extrême mais explicable
# → CONSERVER ou créer une variable "Black Friday"
# → Modéliser séparément si nécessaire
```
**4. Est-ce une mesure défaillante ?**
```python
# Exemple : Température = -50°C en été
# → Erreur de capteur
# → EXCLURE ou CORRIGER
```
---
### Étape 3 : Action
#### Option 1 : Corriger
**Quand** : Erreur de saisie identifiée
**Exemple** :
```python
# Avant (erreur)
Prix = 15000000 # 15 millions pour un 60 m² ??
# Après (correction)
Prix = 150000 # 150k€ → réaliste
# Action : Modifier la valeur dans le fichier source
```
---
#### Option 2 : Conserver
**Quand** : Valeur légitime mais extrême
**Stratégies** :
**A. Transformation**
```python
# Appliquer une transformation log
prix_log = log(Prix)
# Avantages :
# - Réduit l'impact des extrêmes
# - Normalise la distribution
```
**B. Modèle robuste**
```python
# Utiliser des méthodes robustes aux outliers
# - Spearman au lieu de Pearson
# - Médiane au lieu de moyenne
# - Isolation Forest pour la détection
```
**C. Analyse séparée**
```python
# Créer deux modèles
# - Modèle 1 : Données normales
# - Modèle 2 : Outliers (cas particuliers)
```
---
#### Option 3 : Exclure
**Quand** :
- Erreur non corrigeable
- Valeur influente et non représentative
- Mesure défaillante
**Dans l'application** :
1. Cliquez sur l'outlier (🔴 ou 🟣)
2. La ligne est marquée pour exclusion
3. Les prochaines analyses ignoreront cette ligne
4. Les exclusions sont mémorisées
**⚠️ Précautions** :
- Documentez la raison de l'exclusion
- Vérifiez l'impact sur la taille de l'échantillon
- Assurez-vous que l'exclusion est justifiée
---
### Étape 4 : Vérification
#### Avant vs Après
```python
# AVANT (avec outliers)
Moyenne = 26.3
Écart-type = 38.5
Corrélation = 0.45
# APRÈS (sans outliers)
Moyenne = 11.6
Écart-type = 1.1
Corrélation = 0.92
# Impact : L'analyse est plus représentative
```
#### Checklist de validation
- [ ] Les exclusions sont **justifiées** et documentées
- [ ] L'échantillon reste **suffisamment grand** (n > 30)
- [ ] Les résultats sont **plus cohérents**
- [ ] Pas de **sur-correction** (exclure trop de données)
- [ ] Les décisions sont **reproductibles**
---
## Impact sur les Analyses
### 1. Moyenne vs Médiane
```python
# Données avec outlier
[10, 12, 11, 13, 12, 100]
Moyenne = 26.3 📊 Biaisée par l'outlier
Médiane = 12 📊 Robuste
# Règle : Utiliser la médiane en présence d'outliers
```
---
### 2. Corrélation Pearson vs Spearman
```python
# Avec outlier (Pearson)
r_pearson = 0.60 📊 Faible (outlier distord la relation)
# Avec outlier (Spearman)
r_spearman = 0.90 📊 Fort (robuste aux outliers)
# Sans outlier (Pearson)
r_pearson = 0.92 📊 Fort (relation réelle)
# Règle : Utiliser Spearman si outliers présents
```
---
### 3. Régression
#### Impact sur les Coefficients
```python
# RÉGRESSION SANS OUTLIER
Prix = 50000 + 2500×Surface
R² = 0.90
# RÉGRESSION AVEC OUTLIER
Prix = 80000 + 1000×Surface
R² = 0.60
# Impact :
# - Intercept : 50000 → 80000 (biaisé)
# - Surface : 2500 → 1000 (sous-estimé)
# - R² : 0.90 → 0.60 (moins précis)
```
#### Influence (Leverage)
Certains outliers ont un **impact disproportionné** :
```python
# Outlier avec fort leverage
Point : (Surface=1000, Prix=1000000)
# Si exclu :
# Coefficient Surface : 2500 → 2800 (+12%)
# L'outlier "tire" la droite vers lui
```
---
### 4. Tests Statistiques
```python
# Test t (comparaison de moyennes)
# SANS outlier
Groupe A : [10, 12, 11, 13, 12]
Groupe B : [15, 17, 16, 18, 17]
p-value = 0.0001 ✅ Différence significative
# AVEC outlier dans Groupe A
Groupe A : [10, 12, 11, 13, 12, 100] # outlier ajouté
Groupe B : [15, 17, 16, 18, 17]
p-value = 0.15 ❌ Différence non significative
# Impact : L'outlier masque la différence réelle
```
---
## Bonnes Pratiques
### 1. Toujours Visualiser
```python
# Box plot pour détecter visuellement
import matplotlib.pyplot as plt
plt.boxplot(data['Prix'])
plt.show()
# Box plot avec outliers marqués
# ┌─┐
# │ │ ● ← Outlier
# ├─┤
# │ │
# └─┘
```
---
### 2. Ne Pas Exclure Automatiquement
```python
❌ MAUVAIS
if is_outlier(valeur):
exclure(valeur) # Automatique
✅ BON
if is_outlier(valeur):
investiguer(valeur) # Manuel
si erreur:
corriger_ou_exclure()
sinon:
conserver()
```
---
### 3. Documenter les Décisions
```python
# Journal des exclusions
exclusions = {
'ligne_42': {
'raison': 'Erreur de saisie (âge=250)',
'action': 'Corrigé en 25',
'date': '2025-01-11'
},
'ligne_87': {
'raison': 'Capteur défaillant (température=-50)',
'action': 'Exclu',
'date': '2025-01-11'
}
}
```
---
### 4. Comparer Avec/Sans
```python
# Analyse 1 : Tous les données
model1 = regression(data_complete)
r2_1 = 0.75
# Analyse 2 : Sans outliers
model2 = regression(data_sans_outliers)
r2_2 = 0.92
# Conclusion : Les outliers impactent significativement
# → Exclusion justifiée si R² améliore et taille échantillon OK
```
---
### 5. Utiliser des Méthodes Robustes
```python
# Méthodes robustes aux outliers
Moyenne → Médiane
Écart-type → Écart interquartile (IQR)
Pearson → Spearman
OLS → Régression robuste (Huber, RANSAC)
```
---
## Exemples Concrets
### Exemple 1 : Immobilier
**Données** : Prix, Surface, Chambres
```
┌───────┬─────────┬──────────┬──────────┐
│ ID │ Surface │ Prix │ Chambres │
├───────┼─────────┼──────────┼──────────┤
│ 1 │ 60 │ 250000 │ 3 │
│ 2 │ 75 │ 300000 │ 4 │
│ 3 │ 500 🔴 │ 350000 │ 5 │ ← Outlier univarié
│ 4 │ 55 │ 280000 │ 3 │
│ 5 │ 80 │ 320000 │ 4 │
│ 6 │ 70 │ 15000000 🔴│ 3 │ ← Outlier univarié
│ 7 │ 65 │ 290000 │ 3 │
└───────┴─────────┴──────────┴──────────┘
```
**Analyse** :
- **Ligne 3** : Surface = 500 m² → Outlier (trop grand pour l'échantillon)
- **Ligne 6** : Prix = 15M€ → Outlier (prix extrême)
**Action** :
```
Investigation :
- Ligne 3 : Vérifié → Château luxueux (légitime)
- Ligne 6 : Vérifié → Erreur de saisie (15M au lieu de 150k)
Décision :
- Ligne 3 : CONSERVER (valeur réelle)
- Ligne 6 : CORRIGER (150k€)
```
---
### Exemple 2 : E-commerce
**Données** : Âge, Revenu, Montant_Achat
```
┌───────┬──────┬─────────┬──────────────┐
│ ID │ Âge │ Revenu │ Montant_Achat │
├───────┼──────┼─────────┼──────────────┤
│ 1 │ 35 │ 3000 │ 150 │
│ 2 │ 42 │ 4500 │ 200 │
│ 3 │ 28 │ 2500 │ 100 │
│ 4 │ 18 🟣│ 100000 🟣│ 0 🟣 │ ← Outlier multivarié
│ 5 │ 55 │ 5000 │ 250 │
└───────┴──────┴─────────┴──────────────┘
```
**Analyse** :
- **Ligne 4** :
- Âge = 18 (normal)
- Revenu = 100k€ (normal)
- Montant = 0 (normal)
- **MAIS** : Jeune avec très haut revenu et aucun achat → SUSPECT
**Investigation** :
```
Cas 1 : Erreur de saisie (revenu=10000€)
Cas 2 : Compte frauduleux
Cas 3 : Héritage récent (légitime)
Cas 4 : Erreur de catégorisation (professionnel vs personnel)
```
**Action** :
```
Si erreur → Corriger
Si fraude → Exclure et signaler
Si légitime → Créer une variable "Profil_Riche_Jeune"
```
---
### Exemple 3 : Santé
**Données** : IMC, Tension, Cholestérol
```
┌───────┬──────┬─────────┬────────────┐
│ ID │ IMC │ Tension │ Cholestérol│
├───────┼──────┼─────────┼────────────┤
│ 1 │ 22 │ 120 │ 180 │
│ 2 │ 25 │ 130 │ 200 │
│ 3 │ 60 🔴│ 180 🔴 │ 350 🔴 │ ← Outlier univarié
│ 4 │ 23 │ 125 │ 190 │
│ 5 │ 28 │ 140 │ 220 │
└───────┴──────┴─────────┴────────────┘
```
**Analyse** :
- **Ligne 3** : IMC=60 (obésité morbide), Tension=180 (hypertension sévère), Cholestérol=350 (très élevé)
**Investigation** :
```
Cas 1 : Patient réel (pathologie sévère)
Cas 2 : Erreur de mesure (unités ?)
Cas 3 : Données agrégées par erreur
```
**Action** :
```
Si patient réel :
→ CONSERVER et analyser séparément (cas sévères)
Si erreur :
→ CORRIGER ou EXCLURE
```
---
## 🎯 Checklist de Gestion des Outliers
### Détection
- [ ] Identifier les outliers univariés (🔴 cercles rouges)
- [ ] Identifier les outliers multivariés (🟣 cercles violets)
- [ ] Compter le nombre d'outliers
- [ ] Vérifier la proportion (< 5% des données)
### Investigation
- [ ] Vérifier la source de données
- [ ] Rechercher des erreurs de saisie
- [ ] Consulter un expert du domaine
- [ ] Explorer les causes possibles
### Action
- [ ] Corriger les erreurs identifiées
- [ ] Conserver les valeurs légitimes
- [ ] Exclure les vraies anomalies
- [ ] Documenter toutes les décisions
### Validation
- [ ] Comparer les résultats avec/sans
- [ ] Vérifier la taille de l'échantillon final
- [ ] S'assurer que la distribution est cohérente
- [ ] Valider avec des graphiques
---
## 📊 Fonctionnalités de l'Application
### Détection Automatique
L'application détecte automatiquement les outliers à l'importation :
```python
# Méthode 1 : IQR (univarié)
uni_outliers = detect_univariate_outliers(
data,
columns=numeric_columns
)
# Méthode 2 : Isolation Forest (multivarié)
multi_outliers = detect_multivariate_outliers(
data,
columns=numeric_columns
)
# Fusion structurée
result = merge_outliers_structured(uni_outliers, multi_outliers)
```
---
### Interface Utilisateur
#### Indicateurs Visuels
- 🔴 **Cercle rouge** : Outlier univarié (sur la cellule)
- 🟣 **Cercle violet** : Outlier multivarié (sur la ligne)
- 🔴🟣 **Les deux** : Les deux types d'outliers
#### Information au Survol
```javascript
// Exemple de tooltip
{
"index": 42,
"reasons": [
"Column 'Surface' value 500 is outside IQR bounds [32.5, 115.5]",
"Multivariate anomaly detected by Isolation Forest"
]
}
```
---
### Exclusion et Mémorisation
```python
# Marquer une ligne pour exclusion
excluded_indices = [42, 87, 156]
# Ré-analyser sans ces lignes
new_analysis = analyze_with_exclusions(
data,
excluded_indices=excluded_indices
)
# Les exclusions sont mémorisées dans la session
```
---
## 🚀 Conclusion
Les outliers sont à la fois un **défi** et une **opportunité** :
⚠️ **Défi** :
- Peuvent fausser vos analyses
- Nécessitent une investigation minutieuse
- Exiger des décisions subjectives
✅ **Opportunité** :
- Peuvent révéler des phénomènes intéressants
- Signalent des erreurs dans les données
- Permettent d'améliorer la qualité des analyses
**Points clés** :
1. **Toujours investiguer** avant d'exclure
2. **Documenter** vos décisions
3. **Comparer** avec/sans outliers
4. **Utiliser** des méthodes robustes
5. **Visualiser** pour comprendre
---
**Version** : 1.0
**Projet** : Application d'Analyse de Données
🔗 **Voir aussi** : [Guide Corrélation](CORRELATION_GUIDE.md) | [Guide Régression](REGRESSION_GUIDE.md)

226
docs/README.md Normal file
View File

@@ -0,0 +1,226 @@
# 📚 Documentation Utilisateur
Bienvenue dans la documentation complète de l'application d'analyse de données statistiques.
---
## 📖 Guides Disponibles
### 🚀 [Guide Utilisateur Principal](USER_GUIDE.md)
**Point de départ recommandé**
- Démarrage rapide
- Vue d'ensemble des fonctionnalités
- Workflow d'analyse complet
- Cas d'usage pratiques
- FAQ et glossaire
**À lire si vous découvrez l'application**
---
### 🔗 [Guide de la Corrélation](CORRELATION_GUIDE.md)
**Analyser les relations entre variables**
- Qu'est-ce que la corrélation ?
- Les 3 méthodes (Pearson, Spearman, Kendall)
- Interpréter la matrice de corrélation
- Comprendre la multicolinéarité
- P-values et significativité
- Bonnes pratiques et exemples
**À lire pour :** Choisir les bons prédicteurs, éviter la multicolinéarité
---
### 📈 [Guide de la Régression](REGRESSION_GUIDE.md)
**Modéliser et prédire des phénomènes**
- Concepts fondamentaux
- 4 types de modèles (linéaire, logistique, polynomial, exponentielle)
- Configuration du modèle
- Interprétation des coefficients
- Métriques de qualité (R², AIC, BIC)
- Équations exportables (Python, Excel, LaTeX)
- Diagnostics graphiques
- Exemples détaillés
**À lire pour :** Construire des modèles prédictifs robustes
---
### 🔍 [Guide des Outliers](OUTLIER_GUIDE.md)
**Gérer les valeurs aberrantes**
- Définition et types d'outliers
- Méthodes de détection (IQR, Isolation Forest)
- Indicateurs visuels (🔴 rouge, 🟣 violet)
- Processus de gestion
- Impact sur les analyses
- Bonnes pratiques
- Cas concrets
**À lire pour :** Garantir la qualité de vos analyses
---
## 🎯 Parcours Recommandé
### Débutant
```
1. USER_GUIDE.md (Comprendre l'application)
2. CORRELATION_GUIDE.md (Explorer les relations)
3. REGRESSION_GUIDE.md (Premiers modèles)
```
### Intermédiaire
```
1. CORRELATION_GUIDE.md (Multicolinéarité)
2. REGRESSION_GUIDE.md (Modèles avancés)
3. OUTLIER_GUIDE.md (Nettoyage des données)
```
### Expert
```
1. OUTLIER_GUIDE.md (Gestion avancée)
2. REGRESSION_GUIDE.md (Interprétation détaillée)
3. CORRELATION_GUIDE.md (Choix des méthodes)
```
---
## 📊 Résumé des Fonctionnalités
### Corrélation 📊
- Matrice de corrélation avec heatmap
- 3 méthodes (Pearson, Spearman, Kendall)
- Détection de multicolinéarité (≥0.7)
- P-values et significativité
- Export CSV
### Régression 📈
- 4 types de modèles (linéaire, logistique, polynomial, exponentielle)
- Sélection automatique des variables (importance)
- Interactions et termes polynomiaux
- Équations exportables (Python, Excel, LaTeX)
- Graphiques diagnostiques (fit, partial regression, parity plot)
- Métriques complètes (R², coefficients, p-values)
### Outliers 🔍
- Détection univariée (IQR)
- Détection multivariée (Isolation Forest)
- Indicateurs visuels (🔴 rouge, 🟣 violet)
- Processus d'exclusion
- Raisons détaillées
---
## 🔍 Recherche Rapide
### Je veux...
**Comprendre mes données**
→ [Guide Corrélation](CORRELATION_GUIDE.md)
**Prédire une variable**
→ [Guide Régression](REGRESSION_GUIDE.md)
**Nettoyer mes données**
→ [Guide Outliers](OUTLIER_GUIDE.md)
**Choisir les bons prédicteurs**
→ [Guide Corrélation - Multicolinéarité](CORRELATION_GUIDE.md#multicolinéarité)
**Interpréter les coefficients**
→ [Guide Régression - Interprétation](REGRESSION_GUIDE.md#interprétation-des-résultats)
**Comprendre le R²**
→ [Guide Régression - Métriques](REGRESSION_GUIDE.md#métriques-de-qualité-du-modèle)
**Exporter l'équation**
→ [Guide Régression - Équations](REGRESSION_GUIDE.md#équations-du-modèle)
**Gérer les valeurs extrêmes**
→ [Guide Outliers](OUTLIER_GUIDE.md)
---
## 📝 Glossaire
### Termes Clés
- **Corrélation** : Force et direction d'une relation entre deux variables
- **Multicolinéarité** : Forte corrélation entre prédicteurs (problématique)
- **Outlier** : Valeur aberrante qui s'écarte du reste des données
- **R²** : Proportion de variance expliquée par le modèle (0 à 1)
- **P-value** : Probabilité que le résultat soit dû au hasard (< 0.05 = significatif)
- **Coefficient** : Impact moyen d'une variable sur la cible
- **IQR** : Interquartile Range (Q3 - Q1), utilisé pour détecter les outliers
- **Isolation Forest** : Algorithme de détection d'anomalies multivariées
- **Régression** : Méthode pour modéliser la relation entre variables
---
## 🚦 Codes Couleurs
### Dans la documentation
- 📊 **Information** : Définitions et concepts
- ✅ **Bon** : Bonne pratique
- ❌ **Mauvais** : Erreur à éviter
- ⚠️ **Attention** : Point important ou risqué
- 🔍 **Investigation** : Analyse nécessaire
- 🎯 **Objectif** : But à atteindre
### Dans l'application
- 🔴 **Rouge** : Outlier univarié ou corrélation négative forte
- 🟣 **Violet** : Outlier multivarié
- 🟢 **Vert** : Significatif ou fiable
- 🔵 **Bleu** : Corrélation positive forte
---
## 📞 Support et Ressources
### Documentation Technique
- Code source : `/backend/app/core/engine/`
- API endpoints : `/backend/app/api/v1/`
- Frontend : `/frontend/src/features/`
### Standards Statistiques
- [Pearson Correlation](https://en.wikipedia.org/wiki/Pearson_correlation_coefficient)
- [Spearman's Rank](https://en.wikipedia.org/wiki/Spearman%27s_rank_correlation_coefficient)
- [Linear Regression](https://en.wikipedia.org/wiki/Linear_regression)
- [Isolation Forest](https://en.wikipedia.org/wiki/Isolation_forest)
---
## 📅 Mises à Jour
**Version actuelle** : 1.0
**Dernière mise à jour** : Janvier 2026
### Changements récents
- ✅ Documentation complète créée
- ✅ Guides utilisateurs détaillés
- ✅ Exemples concrets
- ✅ Glossaire et parcours recommandés
---
## 🎓 Bonnes Analyses !
Cette documentation est conçue pour vous accompagner à chaque étape de vos analyses statistiques.
**Rappelez-vous** :
- 📊 **Vérifiez toujours** la corrélation avant de régresser
- 🔍 **Investiguez** les outliers avant de les exclure
- 📈 **Interprétez** les coefficients (pas juste le R²)
- ✅ **Documentez** vos décisions
Bonne découverte de l'application !
---
**Version** : 1.0
**Projet** : Application Web d'Analyse de Données
**Plateforme** : Backend Python + Frontend Next.js

1072
docs/REGRESSION_GUIDE.md Normal file
View File

File diff suppressed because it is too large Load Diff

328
docs/USER_GUIDE.md Normal file
View File

@@ -0,0 +1,328 @@
# Guide Utilisateur - Application d'Analyse de Données
📊 **Bienvenue** dans l'application d'analyse de données statistiques. Ce guide vous accompagne pas à pas dans l'utilisation des fonctionnalités principales.
---
## 🚀 Démarrage Rapide
### 1. Importer vos données
- **Formats supportés** : CSV, Excel
- **Cliquez sur** "Upload File" pour charger votre dataset
- Les données sont automatiquement détectées et typées (numérique, catégorique, date)
### 2. Explorer vos données
- Utilisez la **table intelligente** pour visualiser vos données
- Les outliers potentiels sont indiqués par des **cercles colorés** :
- 🔴 **Rouge** : Outlier univarié (valeur extrême dans une colonne)
- 🟣 **Violet** : Outlier multivarié (anomalie globale)
### 3. Lancer une analyse
Cliquez sur le bouton **"Analyse"** dans la barre latérale pour accéder aux outils d'analyse.
---
## 📈 Fonctionnalités Principales
### 1. Matrice de Corrélation 🔗
**Objectif** : Comprendre les relations entre vos variables numériques.
#### Comment l'utiliser ?
1. **Accédez à l'onglet "Corrélation"**
2. **Choisissez la méthode** :
- **Pearson** : Relations linéaires (données normales)
- **Spearman** : Relations monotones (données non-paramétriques)
- **Kendall** : Similarité de rang (petits échantillons)
3. **Interprétez la heatmap** :
- **Rouge foncé** : Forte corrélation positive (0.7 à 1.0)
- **Bleu foncé** : Forte corrélation négative (-0.7 à -1.0)
- **Bordure rouge** ⚠️ : Multicolinéarité détectée (≥0.7)
4. **Filtres avancés** :
- **Seuil minimum** : Affichez seulement les corrélations > X
- **Significatif seulement** : p-value < 0.05
#### ⚠️ Alertes Multicolinéarité
Si vous voyez une **bordure rouge** entre deux prédicteurs :
- **Ne les utilisez pas ensemble** dans une régression
- Choisissez la variable la plus corrélée avec votre cible
- Exemple : Si `Taille` et `Poids` sont corrélés à 0.85, gardez-en un seul
#### Export
Cliquez sur **"Exporter CSV"** pour télécharger les résultats.
---
### 2. Régression Statistique 📉
**Objectif** : Modéliser et prédire une variable cible.
#### Étape 1 : Configuration du modèle
Dans le panneau de configuration avancée :
**1. Choisissez votre type de modèle** :
- **Linéaire** : Relations linéaires simples
- **Logistique** : Cible binaire (oui/non, 0/1)
- **Polynomial** : Relations courbes (degrés 2-5)
- **Exponentielle** : Croissance/décroissance exponentielle
**2. Sélectionnez votre Variable Cible (Y)** :
- La variable que vous voulez expliquer/prédire
- Pour linéaire/polynomial/exponentielle : doit être **numérique continue**
- Pour logistique : doit être **catégorique ou binaire**
**3. Choisissez vos Prédicteurs (X)** :
- Les variables qui expliquent Y
- L'application recommande automatiquement les **5 meilleures variables** basées sur leur importance
- Désélectionnez les variables avec multicolinéarité
#### Étape 2 : Options avancées
**Pour Polynomial** :
- **Degré du polynôme** : 2 (quadratique) à 5
- + degré = + complexité (risque de sur-apprentissage)
**Pour Linéaire/Polynomial** :
- **Inclure interactions** : Crée des termes croisés (x1*x2)
- Utile pour capturer les effets combinés de variables
#### Étape 3 : Lancer l'analyse
Cliquez sur **"Lancer l'Analyse"** et attendez les résultats.
---
## 📊 Interpréter les Résultats de Régression
### 1. Métriques de Qualité
| Métrique | Description | Valeur Idéale |
|----------|-------------|---------------|
| **R-Squared** | Proportion de variance expliquée | 0.7 - 1.0 |
| **Adj. R-Squared** | R² ajusté pour le nombre de variables | Proche de R² |
| **AIC / BIC** | Critères d'information (plus bas = mieux) | Comparer modèles |
#### R-Squared Guide
- **0.90 - 1.00** : Excellent ajustement
- **0.70 - 0.90** : Bon ajustement
- **0.50 - 0.70** : Ajustement modéré
- **< 0.50** : Faible ajustement
---
### 2. Coefficients du Modèle
Le tableau des coefficients indique l'impact de chaque variable :
| Colonne | Signification |
|---------|---------------|
| **Variable** | Nom de la variable ou constante |
| **Coefficient** | Impact moyen sur Y (si X augmente de 1) |
| **P-Value** | Significativité statistique |
| **Fiabilité** | FIABLE si p < 0.05 |
#### Comment lire les coefficients ?
**Exemple** : `Y = 10 + 2.5*X1 - 1.3*X2`
- **Constante (10)** : Valeur de Y quand tous les X = 0
- **X1 (+2.5)** : Si X1 augmente de 1, Y augmente de 2.5
- **X2 (-1.3)** : Si X2 augmente de 1, Y diminue de 1.3
⚠️ **Important** : Un coefficient n'est fiable que si **p-value < 0.05** (FIABLE)
---
### 3. Équation du Modèle
L'application génère automatiquement l'équation dans 3 formats :
#### LaTeX (Mathématique)
Pour vos rapports et publications :
```
y = 1.234567 + 2.345678x_{0} + 3.456789x_{0}^{2}
```
#### Python (Code)
Pour implémenter le modèle en Python :
```python
y = 1.234567 + 2.345678*x0 + 3.456789*x0**2
```
#### Excel (Formule)
Pour utiliser dans Excel/Google Sheets :
```
=1.234567 + 2.345678*A1 + 3.456789*A1^2
```
**Bouton "Copier"** : Copiez l'équation directement dans votre presse-papier !
---
### 4. Graphiques de Diagnostic
#### Fit Plot (Régression univariée)
- **Points gris** : Vos données réelles
- **Ligne bleue** : Le modèle ajusté
- Vérifiez que la ligne suit bien la tendance des points
#### Partial Regression Plot (Régression multivariée)
- Montre l'**effet isolé** de chaque variable
- Contrôle l'effet des autres variables
- La **pente** = coefficient du modèle
- Utilisez le sélecteur pour changer de variable
#### Parity Plot (Validation)
- **Diagonale rouge** : Prédictions parfaites (Y = X)
- **Points violets** : Vos observations
- Plus les points sont proches de la diagonale = meilleur modèle
- **Écart à la diagonale** = erreur de prédiction
---
## 🔍 Détection et Gestion des Outliers
### Types d'Outliers
#### 1. Outliers Univariés (IQR)
Détection basée sur l'écart interquartile :
- **Calcul** : Q1 - 1.5×IQR (bas) / Q3 + 1.5×IQR (haut)
- **Indicateur** : 🔴 Cercle rouge
- **Action** : Vérifiez la valeur, corrigez ou excluez
#### 2. Outliers Multivariés (Isolation Forest)
Détection basée sur les combinaisons de variables :
- **Algorithme** : Isolation Forest
- **Indicateur** : 🟣 Cercle violet
- **Action** : Anomalie globale à investiguer
### Processus d'Exclusion
1. **Identifiez** les outliers dans la table
2. **Survolez** pour voir le détail (raison)
3. **Cliquez sur l'outlier** pour le marquer
4. **Réexécutez** l'analyse sans ces points
**Note** : Les outliers exclus sont mémorisés et ne réapparaissent pas.
---
## 💡 Bonnes Pratiques
### Avant la Régression
✅ **TOUJOURS** vérifier la matrice de corrélation
✅ **Éviter** la multicolinéarité (corrélations ≥ 0.7 entre prédicteurs)
✅ **Choisir** des prédicteurs corrélés avec la cible
✅ **Exclure** les outliers extrêmes
### Pendant l'Analyse
✅ **Commencer** par un modèle linéaire simple
✅ **Augmenter** la complexité progressivement (polynomial, interactions)
✅ **Surveiller** le R² ajusté (il diminue si variables inutiles)
✅ **Vérifier** les p-values (< 0.05 = fiable)
### Après l'Analyse
✅ **Valider** avec le Parity Plot (points près de la diagonale)
✅ **Interpréter** les coefficients (sens et magnitude)
✅ **Exporter** l'équation pour utilisation future
✅ **Documenter** les décisions (variables exclues, outliers retirés)
---
## 🎯 Cas d'Usage
### Exemple 1 : Prédire le Prix Immobiliers
**Données** : Prix, Surface, Chambres, Quartier, Année
1. **Corrélation** : Prix vs Surface (forte corrélation)
2. **Régression linéaire** :
- Y = Prix
- X = Surface, Chambres
- Équation : `Prix = 50000 + 2500*Surface + 15000*Chambres`
3. **Utilisation** : Prédire le prix d'un appartement de 60m² avec 2 chambres
- `Prix = 50000 + 2500*60 + 15000*2 = 215000€`
### Exemple 2 : Probabilité de Réclamation
**Données** : Âge, Montant, Historique, Réclamation (oui/non)
1. **Régression logistique** :
- Y = Réclamation (0/1)
- X = Âge, Montant, Historique
2. **Résultat** : Probabilité de réclamation = f(Âge, Montant, Historique)
### Exemple 3 : Relation Courbe (Ventes vs Publicité)
**Données** : Ventes, Budget_Pub, Concurrence
1. **Corrélation** : Forte mais non-linéaire
2. **Régression polynomial (degré 2)** :
- Y = Ventes
- X = Budget_Pub
- Équation : `Ventes = 1000 + 5*Budget - 0.01*Budget²`
3. **Interprétation** : Rendements décroissants après un certain budget
---
## ❓ Questions Fréquentes
### Mon R² est faible (< 0.5). Que faire ?
- **Vérifiez** : Avez-vous les bons prédicteurs ?
- **Testez** : Ajoutez des variables ou essayez polynomial
- **Nettoyez** : Supprimez les outliers
- **Acceptez** : Le modèle n'explique peut-être pas tout (variables manquantes)
### Une variable a une p-value > 0.05. Je la garde ?
**Non** en général :
- Le coefficient n'est pas statistiquement significatif
- Le modèle est plus robuste sans elle
- Exception : Avis d'expert justifiant son importance
### Combien de prédicteurs choisir ?
- **Règle** : 1 prédicteur pour 10-20 observations
- **Maximum** : n/10 (n = taille échantillon)
- **Qualité > Quantité** : Préférez 5 variables fiables à 20 variables instables
### Quand utiliser polynomial vs linéaire ?
- **Linéaire** : Relation droite (premier choix)
- **Polynomial** : Relation courbe évidente sur le scatter plot
- **Attention** : Degré trop élevé = sur-apprentissage
---
## 📞 Support et Ressources
### Documentation Détaillée
- 📊 **[Corrélation](CORRELATION_GUIDE.md)** : Guide complet des coefficients de corrélation
- 📈 **[Régression](REGRESSION_GUIDE.md)** : Modèles, interprétation, équations
- 🔍 **[Outliers](OUTLIER_GUIDE.md)** : Méthodes de détection et gestion
### Glossaire
- **Corrélation** : Force et direction d'une relation entre deux variables
- **Multicolinéarité** : Forte corrélation entre prédicteurs (problématique)
- **P-value** : Probabilité que le résultat soit dû au hasard (< 0.05 = significatif)
- **R²** : Proportion de variance expliquée par le modèle (0 à 1)
- **Outlier** : Observation anormale qui s'écarte du reste des données
- **Isolation Forest** : Algorithme de détection d'anomalies multivariées
- **IQR** : Interquartile Range (Q3 - Q1), utilisé pour détecter les extrêmes
---
**Version** : 1.0
**Dernière mise à jour** : Janvier 2026
**Plateforme** : Application Web d'Analyse de Données
🎓 **Bonnes analyses !**