Crack Usage Binary Classifier

TensorFlow-based binary classification pipeline optimized for Apple Silicon to predict crack cocaine usage from demographic and personality data.

Features

• Feature Engineering: Automated creation of risk scores, personality clusters, and interaction features
• EDA Visualizations: 8 comprehensive plots exploring feature distributions and correlations
• Apple Silicon Optimization: Uses tensorflow-metal for GPU acceleration on M1/M2/M3 chips
• Class Imbalance Handling: Automatic class weight calculation
• Feature Importance Analysis: Three methods (Permutation, SHAP, Integrated Gradients)

Installation

# Install dependencies
pip install -e .

# Or with uv
uv pip install -e .

Usage

python main.py

Output

The pipeline generates:

Models

• models/best_model.keras - Trained model checkpoint

Input Data Plots (plots/input_data/)

• eda_target_distribution.png - Class imbalance visualization
• eda_demographics.png - Age, Gender, Education, Country, Ethnicity
• eda_personality_dist.png - Big Five personality traits
• eda_behavioral_scores.png - Impulsive & Sensation Seeking
• eda_correlation_heatmap.png - Feature correlations
• eda_pairplot.png - Pairwise relationships
• eda_boxplots.png - Features by crack usage
• eda_violins.png - Distribution shapes

Feature Importance Plots (plots/feature_importance/)

• training_history.png - Loss, accuracy, AUC curves
• evaluation_metrics.png - ROC, PR curves, confusion matrix
• fi_permutation.png - Permutation importance bar chart
• fi_shap_summary.png - SHAP beeswarm plot
• fi_shap_bar.png - Mean absolute SHAP values
• fi_shap_dependence.png - Top feature dependence plots
• fi_shap_force.png - SHAP force plots for individual predictions
• fi_integrated_gradients_bar.png - Integrated gradients bar chart
• fi_integrated_gradients_heatmap.png - Per-sample attribution heatmap
• fi_method_comparison_bars.png - Rankings comparison (grouped bars)
• fi_method_comparison_heatmap.png - Rankings comparison (heatmap)
• fi_method_comparison_table.png - Summary table with average ranks
• feature_importance_all_methods.csv - All methods combined
• feature_importance_permutation.csv - Permutation importance only

Data

Uses Drug_Consumption.csv with demographic (Age, Gender, Education, Country, Ethnicity) and personality features (Big Five, Impulsivity, Sensation Seeking) to predict crack usage (binary: Never Used vs Used).

Architecture

See PIPELINE_ARCHITECTURE.md and VISUALIZATION_PLAN.md for detailed documentation.