Installation Guide

Getting MoodLens Running on Your Machine

Follow these in order. Do not skip step three, that is where most people get stuck.

Prerequisites

• Python 3.8 or newer. Grab it from python.org if you do not have it. On Windows, tick the "Add Python to PATH" box during install or nothing will work from the terminal later.
• pip — comes bundled with Python, you already have it.
• Jupyter Notebook for the training step. Install it with pip install notebook if it is not already there.
• Any code editor. VS Code is fine.
• An emotion-labelled dataset CSV. Kaggle's emotion detection datasets work, or anything with a text column and an emotion column.

Step 1 — Open the project folder

Extract the downloaded zip somewhere sensible. Not Downloads. Then open a terminal inside that folder.

cd MoodLens

Step 2 — Create a virtual environment

This keeps the project's packages separate from everything else on your system.

python -m venv venv

Then activate it. On Windows:

venv\Scripts\activate

On macOS or Linux:

source venv/bin/activate

You will know it worked because (venv) appears at the start of your terminal line.

Step 3 — Install the dependencies

pip install -r requirements.txt

Flask, scikit-learn, NLTK, pandas and the rest all come down together. Takes a couple of minutes on decent internet.

Step 4 — Download the NLTK language data

This is separate from the pip install and it trips up almost everybody. Run this exact command:

python -c "import nltk; nltk.download('punkt'); nltk.download('stopwords'); nltk.download('wordnet'); nltk.download('omw-1.4')"

Step 5 — Add your dataset

Drop your CSV into the data/ folder. Open it once in Excel first and confirm the column names match what the training notebook expects. Renaming a column now saves you an hour later.

Step 6 — Train the model

jupyter notebook emotion_detection_training.ipynb

Run every cell top to bottom. When it finishes, check that models/ now contains four files: tfidf_vectorizer.pkl, label_encoder.pkl, logistic_regression_model.pkl and metadata.pkl. If any one is missing, the app will not start.

Step 7 — Run the app

python app.py

Open http://localhost:5000 in your browser.

Optional — Run the Transfer Lab from the terminal

Useful for generating screenshots for your report.

python -m transfer.engine --run-all

Or test a single domain pair:

python -m transfer.engine --train social --test forum

Results get cached into artifacts/ and the web Transfer Lab reads from there, so run this once before your demo and the page loads instantly.

Common Issues

"ModuleNotFoundError: No module named flask"

Your virtual environment is not active. Look for (venv) in the terminal. If it is missing, run the activate command from step 2 again. This happens every time you close and reopen the terminal.

"Resource punkt not found" or a similar LookupError

Step 4 did not complete. Re-run the NLTK download command. If your college network blocks it, connect to mobile hotspot for that one command.

Predictions page loads but returns an error on submit

Nine times out of ten the pickle files are missing or were built with a different scikit-learn version. Re-run the training notebook inside the same virtual environment you use to run the app.

Port 5000 already in use

Something else is holding the port, and on macOS it is usually AirPlay Receiver. Turn that off in system settings, or change the port in app.py to 5001.

How to Check It Is Actually Working

1. Home page loads with the soft shadowed cards visible. If it looks flat and grey, your CSS is not loading.
2. Go to the predict page and type something obvious like "I got my results and I am so happy right now". You should get happiness back with a high confidence bar.
3. Now try "I hate this, everything went wrong today" and confirm the prediction flips.
4. Check that the history panel lists both predictions.
5. Open the Transfer Lab page and confirm the matrix renders with numbers, not empty cells. Empty cells mean you have not run the engine yet.

All five working means you are done. Take screenshots now while it is running, not on submission day.