Mushroom Edibility Classifier using ML

Every year, foragers are poisoned by wild mushrooms that resemble edible species — and a single wrong call can be fatal. Distinguishing edible from poisonous mushrooms by eye demands expert mycological knowledge that most people simply do not have. The classic UCI mushroom dataset captures that expert knowledge as 22 categorical morphological attributes (odor, gill color, spore print color, cap surface and more) across 8,124 recorded specimens, making it one of the most instructive tabular classification problems in machine learning. This project turns it into a complete student build: Random Forest and Gradient Boosting models trained on the full dataset, wrapped in a demo that classifies specimen mushrooms with explainable feature evidence. The demo shows the real field photographs, the 22-feature vector behind each prediction, and which attributes carried the most weight — so the viva can discuss why odor dominates the decision and where the model can still be wrong.

1. The 8,124 UCI mushroom records are loaded and the 22 categorical attributes are one-hot encoded; the edible/poisonous class label is kept as the target.
2. Data is split 80/20 stratified, preserving the 51.8/48.2 class balance in train and test sets.
3. A Random Forest (100 estimators) is trained; a Gradient Boosting model (200 rounds) is trained as the comparison baseline.
4. The notebook evaluates both on the held-out split — accuracy, precision, recall, F1 and the confusion matrix — and logs feature importances.
5. At inference, the demo app maps a specimen's 22 attributes to the encoded vector, runs the forest, and renders the verdict with confidence and top contributing features.
6. The demo's dataset and training views read the same CSVs the notebook writes, so every number on screen traces back to the student's build.

Tech stack:

• Python 3.10, scikit-learn (Random Forest, Gradient Boosting, metrics), pandas, NumPy
• Matplotlib (class balance, importances, confusion matrix)
• Single-file HTML/CSS/JS demo app (classifier, dataset explorer, evaluation views)
• UCI Mushroom Classification dataset (Schlimmer, 1987)
• Real specimen photographs embedded in the demo

• [Specimen classifier] Pick a real photographed specimen and get an edible/poisonous verdict with a confidence bar and the morphological evidence behind it.
• [Random Forest pipeline] 100-estimator forest on one-hot encoded categorical features; all hyperparameters exposed in the notebook.
• [Gradient Boosting baseline] A second model for the viva comparison — similar headline accuracy, different training cost and feature-importance story.
• [Dataset explorer view] Class balance (4,208 edible vs 3,916 poisonous), all 22 attribute definitions, and the near-balanced split that makes accuracy a fair metric.
• [Feature-importance view] Odor, spore-print color and gill color ranked by the trained models — the classic mycology result, reproduced by the build.
• [Confusion matrix view] Held-out 20% split results showing exactly where the (rare) errors land.
• [Safety framing] Every result carries the explicit warning that software output is not food-safety advice — an honest-scope feature examiners respect.
• [Full evaluation logging] Accuracy, precision, recall, F1 and the confusion matrix computed on the held-out split — never pre-claimed.

• Complete source code (preprocessing, encoding, training, evaluation, demo app)
• Jupyter training and evaluation notebook (buyer-run procedure: train, evaluate, inspect errors)
• Project report PDF (background, UCI dataset analysis, methodology, evaluation, error analysis)
• PPT presentation for final review
• Viva Q&A preparation document (tree ensembles, encoding, feature importance, class balance, evaluation metrics)
• Setup guide (environment, dataset download, training, running the demo)

• The model classifies from the 22 recorded morphological attributes — it cannot score a photograph alone, and it knows nothing about species outside the UCI encoding.
• The dataset is from 1987 and covers a limited species set; real-world foraging involves lookalike species the data does not represent.
• A prediction is statistical, not a safety certificate: the project explicitly refuses the "is it safe to eat" framing and directs users to expert mycologists.
• Poisonous-class recall matters more than headline accuracy — the report discusses this cost asymmetry and how the threshold was chosen.
• Near-perfect accuracy on this dataset is expected for tree ensembles; the viva value is in the methodology and honest scope discussion, not in beating a benchmark.