Skip to content

USAGE‐GUIDE

Jump to bottom
SRIJA DE CHOWDHURY edited this page Dec 29, 2025 · 1 revision

📚 Usage Guide

Complete Guide to Using the Advanced Depression Predictor Model

Difficulty Language API

🎯 Quick Navigation

🌟 Basic Usage

Simple predictions Get started fast

🚀 Advanced Usage

Training & tuning Custom workflows

🌐 API Usage

REST endpoints Integration guide

🌟 Basic Usage

Example 1: Simple Prediction

from depression_predictor import DepressionPredictor
import pandas as pd

# 1️⃣ Initialize the model
model = DepressionPredictor()

# 2️⃣ Load your data
data = pd.read_csv('your_data.csv')

# 3️⃣ Make predictions
predictions = model.predict(data)

# 4️⃣ Display results
print(f"✅ Predictions completed: {len(predictions)} samples")
print(predictions)

Expected Output:

✅ Predictions completed: 100 samples
[0, 1, 0, 0, 1, 1, 0, ...]

Example 2: Single Sample Prediction

📝 Prepare Sample

sample = {
    # Demographics
    'age': 28,
    'gender': 'female',
    'education': 'bachelors',
    'employment': 'full_time',
    'marital_status': 'single',
    
    # Behavioral
    'sleep_hours': 5. 5,
    'activity_level': 'low',
    'social_interaction': 'minimal',
    'screen_time': 8,
    
    # Symptoms
    'mood_score': 3,
    'energy_level': 2,
    'concentration': 4,
    'interest_level': 3,
    
    # ...  other features
}

🎯 Get Prediction

# Predict
result = model.predict_single(sample)

# Pretty print results
print(f"""
╔════════════════════════════════╗
║   🎯 PREDICTION RESULTS        ║
╠════════════════════════════════╣
║ Risk Level:       {result['prediction']}              ║
║ Probability:     {result['probability']:.1%}       ║
║ Confidence:      {result['confidence']}          ║
║ Timestamp:       {result['timestamp']}    ║
╚════════════════════════════════╝
""")

Output:

╔════════════════════════════════╗
║   🎯 PREDICTION RESULTS        ║
╠════════════════════════════════╣
║ Risk Level:      1              ║
║ Probability:      76.3%          ║
║ Confidence:       high           ║
║ Timestamp:        2025-12-29...   ║
╚════════════════════════════════╝

Example 3: Load Pre-trained Model

# 🔹 Option 1: Load from file path
model = DepressionPredictor(model_path='models/best_model.h5')

# 🔹 Option 2: Load after initialization
model = DepressionPredictor()
model.load('models/best_model.h5')

# 🔹 Option 3: Load with config
model = DepressionPredictor(
    model_path='models/best_model.h5',
    config='config/production.yml'
)

# ✅ Verify model loaded
print(f"✅ Model loaded successfully!")
print(f"📦 Version: {model.version}")
print(f"🎯 Accuracy: {model. accuracy:.1%}")

Example 4: Batch Processing

import pandas as pd
from tqdm import tqdm

# Load large dataset
data = pd.read_csv('large_dataset.csv')
print(f"📊 Processing {len(data)} samples...")

# Process in batches
batch_size = 100
results = []

for i in tqdm(range(0, len(data), batch_size)):
    batch = data.iloc[i:i+batch_size]
    predictions = model.predict(batch)
    results.extend(predictions)

# Save results
output = pd.DataFrame({
    'id': data['id'],
    'prediction': results,
    'timestamp': pd. Timestamp.now()
})
output.to_csv('predictions. csv', index=False)
print("✅ Results saved to predictions.csv")

Output:

📊 Processing 10000 samples...
100%|████████████████████████| 100/100 [00:45<00:00,  2.21it/s]
✅ Results saved to predictions.csv

🚀 Advanced Usage

Training a New Model

📖 Full Training Example 
from depression_predictor import DepressionPredictor
from depression_predictor.data import load_dataset
from depression_predictor.callbacks import CustomCallback

# 1️⃣ Load training data
print("📥 Loading dataset...")
X_train, y_train = load_dataset('train')
X_test, y_test = load_dataset('test')

print(f"✅ Training samples: {len(X_train)}")
print(f"✅ Testing samples: {len(X_test)}")

# 2️⃣ Initialize model
model = DepressionPredictor()

# 3️⃣ Configure training
training_config = {
    'epochs': 100,
    'batch_size': 32,
    'validation_split': 0.2,
    'callbacks': [
        'early_stopping',
        'model_checkpoint',
        'tensorboard'
    ]
}

# 4️⃣ Train model
print("🚀 Starting training...")
history = model.train(
    X_train, y_train,
    validation_data=(X_test, y_test),
    **training_config
)

# 5️⃣ Evaluate
print("📊 Evaluating model...")
results = model.evaluate(X_test, y_test)
print(f"""
Training Complete!  🎉
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📈 Final Training Accuracy:    {results['train_accuracy']:.2%}
📉 Final Training Loss:       {results['train_loss']:.4f}
✅ Validation Accuracy:       {results['val_accuracy']:. 2%}
📉 Validation Loss:           {results['val_loss']:.4f}
🎯 Test Accuracy:             {results['test_accuracy']:. 2%}
⏱️  Training Time:             {results['training_time']}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
""")

# 6️⃣ Save model
model. save('models/my_custom_model.h5')
print("💾 Model saved successfully!")

Hyperparameter Tuning

from depression_predictor.tuning import GridSearch, RandomSearch

# Define parameter grid
param_grid = {
    'learning_rate': [0.001, 0.01, 0.1],
    'batch_size': [16, 32, 64],
    'dropout_rate': [0.2, 0.3, 0.4],
    'hidden_units': [64, 128, 256]
}

# Option 1: Grid Search (exhaustive)
print("🔍 Running Grid Search...")
grid_search = GridSearch(param_grid)
best_params_grid = grid_search.fit(X_train, y_train)

# Option 2: Random Search (faster)
print("🎲 Running Random Search...")
random_search = RandomSearch(param_grid, n_iter=20)
best_params_random = random_search.fit(X_train, y_train)

# Display results
print(f"""
🏆 Best Parameters Found:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Learning Rate:     {best_params_random['learning_rate']}
Batch Size:       {best_params_random['batch_size']}
Dropout Rate:     {best_params_random['dropout_rate']}
Hidden Units:      {best_params_random['hidden_units']}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Best Accuracy:    {random_search.best_score_:.2%}
""")

# Train final model with best params
final_model = DepressionPredictor(**best_params_random)
final_model.train(X_train, y_train)

Custom Preprocessing

from depression_predictor.preprocessing import CustomPreprocessor

# Create custom preprocessor
preprocessor = CustomPreprocessor()

# Add custom transformations
preprocessor.add_transformation('age', lambda x: (x - 18) / 62)  # Normalize age
preprocessor. add_transformation('sleep_hours', lambda x: np.clip(x, 0, 12))  # Clip outliers

# Custom feature engineering
def create_interaction_features(data):
    """Create custom interaction features"""
    data['sleep_activity_interaction'] = data['sleep_hours'] * data['activity_level']
    data['mood_energy_ratio'] = data['mood_score'] / (data['energy_level'] + 1)
    return data

preprocessor.add_feature_engineer(create_interaction_features)

# Apply preprocessing
X_processed = preprocessor.fit_transform(X_raw)

# Use with model
model = DepressionPredictor(preprocessor=preprocessor)
model.train(X_processed, y_train)

Model Interpretation

from depression_predictor.interpretation import FeatureImportance, SHAP

# 1️⃣ Feature Importance
fi = FeatureImportance(model)
importance_df = fi.calculate()

print("🔝 Top 10 Most Important Features:")
print(importance_df.head(10))

# 2️⃣ SHAP Values
shap_explainer = SHAP(model)
shap_values = shap_explainer.explain(X_test)

# Visualize
shap_explainer.plot_summary()
shap_explainer.plot_force(sample_index=0)

# 3️⃣ Individual Prediction Explanation
explanation = model.explain_prediction(sample)
print(f"""
🔍 Prediction Explanation:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Prediction: {explanation['prediction']}
Top Contributing Features:
  1. {explanation['top_features'][0]['name']}: {explanation['top_features'][0]['contribution']}
  2. {explanation['top_features'][1]['name']}: {explanation['top_features'][1]['contribution']}
  3. {explanation['top_features'][2]['name']}: {explanation['top_features'][2]['contribution']}
""")

🌐 API Usage

REST API Endpoints

1️⃣ Single Prediction

Request:

curl -X POST \
  http://localhost:5000/api/v1/predict \
  -H 'Content-Type: application/json' \
  -d '{
    "age": 28,
    "gender": "female",
    "sleep_hours": 5.5,
    "mood_score": 3,
    "energy_level": 2
  }'

Response:

{
  "status": "success",
  "prediction": 1,
  "probability": 0.763,
  "confidence": "high",
  "risk_level": "elevated",
  "timestamp": "2025-12-29T10:30:00Z",
  "model_version": "1.0. 0"
}

2️⃣ Batch Prediction

curl -X POST \
  http://localhost:5000/api/v1/batch-predict \
  -H 'Content-Type: application/json' \
  -d '{
    "samples": [
      {"age": 28, "sleep_hours": 5.5, ... },
      {"age": 45, "sleep_hours": 7.0, ...},
      {"age": 32, "sleep_hours": 6.0, ...}
    ]
  }'

Response:

{
  "status": "success",
  "total_samples": 3,
  "predictions": [
    {"id": 0, "prediction": 1, "probability": 0.763},
    {"id": 1, "prediction": 0, "probability": 0.234},
    {"id": 2, "prediction": 0, "probability": 0.412}
  ],
  "processing_time_ms": 145
}

3️⃣ Model Information

curl http://localhost:5000/api/v1/model/info

Response:

{
  "model_name": "Advanced Depression Predictor",
  "version": "1.0.0",
  "accuracy": 0.892,
  "auc": 0.920,
  "f1_score": 0.864,
  "last_trained": "2025-12-01T00:00:00Z",
  "features_count": 50,
  "total_parameters": 12789
}

Python API Integration

import requests
import json

class DepressionPredictorAPI:
    """Wrapper for Depression Predictor API"""
    
    def __init__(self, base_url="http://localhost:5000/api/v1"):
        self.base_url = base_url
        
    def predict(self, sample):
        """Make a single prediction"""
        response = requests.post(
            f"{self.base_url}/predict",
            json=sample
        )
        return response.json()
    
    def batch_predict(self, samples):
        """Make batch predictions"""
        response = requests.post(
            f"{self.base_url}/batch-predict",
            json={"samples": samples}
        )
        return response.json()
    
    def get_model_info(self):
        """Get model information"""
        response = requests.get(f"{self.base_url}/model/info")
        return response.json()

# Usage
api = DepressionPredictorAPI()

# Single prediction
result = api.predict({
    "age": 28,
    "sleep_hours": 5.5,
    # ... other features
})
print(f"Prediction: {result['prediction']}")
print(f"Probability: {result['probability']:.1%}")

# Batch prediction
results = api.batch_predict([sample1, sample2, sample3])
print(f"Processed {results['total_samples']} samples")

📊 Visualization

Plotting Results

from depression_predictor.visualization import (
    plot_predictions,
    plot_feature_importance,
    plot_confusion_matrix,
    plot_roc_curve
)

# 1️⃣ Prediction Distribution
plot_predictions(predictions, save_path='plots/predictions.png')

# 2️⃣ Feature Importance
plot_feature_importance(
    model,
    top_n=15,
    save_path='plots/feature_importance.png'
)

# 3️⃣ Confusion Matrix
plot_confusion_matrix(
    y_true=y_test,
    y_pred=predictions,
    save_path='plots/confusion_matrix.png'
)

# 4️⃣ ROC Curve
plot_roc_curve(
    y_true=y_test,
    y_score=probabilities,
    save_path='plots/roc_curve.png'
)

# 5️⃣ Training History
from depression_predictor.visualization import plot_training_history

plot_training_history(
    history,
    metrics=['loss', 'accuracy', 'auc'],
    save_path='plots/training_history.png'
)

💡 Best Practices

✅ DO

  • ✔️ Validate input data before prediction
  • ✔️ Use batch processing for large datasets
  • ✔️ Handle missing values appropriately
  • ✔️ Monitor model performance over time
  • ✔️ Use predictions as decision support only
  • ✔️ Involve healthcare professionals
  • ✔️ Respect user privacy
  • ✔️ Document all preprocessing steps

❌ DON'T

  • ❌ Use predictions as sole diagnostic tool
  • ❌ Ignore prediction confidence scores
  • ❌ Skip data validation
  • ❌ Store sensitive personal information
  • ❌ Use outdated models in production
  • ❌ Ignore class imbalance
  • ❌ Deploy without ethical review
  • ❌ Forget to retrain periodically

🔧 Advanced Configuration

Custom Configuration File

# config/custom. yml

# Model Settings
model:
  architecture: deep_neural_network
  input_dim: 50
  hidden_layers:  [128, 64, 32]
  dropout_rates: [0.3, 0.2, 0.0]
  activation:  relu
  output_activation: sigmoid
  
# Training Settings  
training:
  optimizer: adam
  learning_rate: 0.001
  batch_size: 32
  epochs: 100
  validation_split: 0.2
  class_weights: {0: 1.0, 1: 1.5}
  
# Callbacks
callbacks:
  early_stopping:
    enabled: true
    patience: 10
    monitor: val_loss
  
  model_checkpoint:
    enabled: true
    filepath: models/checkpoints/model_{epoch: 02d}. h5
    save_best_only: true
    
  reduce_lr:
    enabled: true
    factor: 0.5
    patience: 5
    min_lr: 0.00001

# Data Settings
data:
  train_path: data/train. csv
  test_path: data/test.csv
  features_config:  config/features.json
  
# Preprocessing
preprocessing:
  numerical: 
    missing_strategy: median
    scaling: standard
    outlier_method: iqr
    
  categorical:
    missing_strategy: mode
    encoding: onehot
    handle_unknown: ignore
    
# Output Settings
output:
  save_predictions: true
  output_dir: results/
  log_level: INFO
  verbose: 1

Load Custom Config:

model = DepressionPredictor(config='config/custom.yml')

🐛 Troubleshooting

❌ Error: "Invalid input shape"

Problem: Input data doesn't match expected feature count

Solution:

# Check expected features
print(f"Expected features: {model.feature_names}")
print(f"Your features: {list(your_data.columns)}")

# Ensure all features are present
missing_features = set(model.feature_names) - set(your_data.columns)
if missing_features:
    print(f"Missing features: {missing_features}")
❌ Error: "Model returns NaN predictions"

Problem: Invalid or extreme input values

Solution:

# Check for invalid values
print(your_data.describe())
print(your_data.isnull().sum())

# Clean data
your_data = your_data.dropna()
your_data = your_data.replace([np.inf, -np. inf], np.nan).dropna()
⚠️ Warning: "Low prediction confidence"

Problem: Model unsure about prediction

Solution:

# Check confidence score
if result['confidence'] == 'low':
    print("⚠️ Low confidence prediction")
    print("Consider:")
    print("- Collecting more features")
    print("- Validating input data quality")
    print("- Consulting domain expert")

📚 Code Examples Repository

All examples are available in the repository:

examples/
├── 01_basic_prediction.py
├── 02_batch_processing.py
├── 03_model_training.py
├── 04_hyperparameter_tuning.py
├── 05_api_integration.py
├── 06_visualization.py
├── 07_custom_preprocessing.py
└── 08_model_interpretation.py

Run examples:

python examples/01_basic_prediction. py

🎓 Next Steps

| Level | Next Topic | Time | |: -----:|------------|------| | 🟢 Beginner | API Reference | 15 min | | 🟡 Intermediate | Model Architecture | 20 min | | 🔴 Advanced | Performance Metrics | 25 min |

Clone this wiki locally