Quiz Platform - Data Literacy Study

A Flask-based web application for conducting a data literacy study with contextualized visualizations and sentiment analysis.

📋 Table of Contents

• Prerequisites
• Installation
• Configuration
• Running the Application
• Data Analysis
• Project Structure

🔧 Prerequisites

• Python 3.11 or higher
• PostgreSQL database (local or remote, e.g., Supabase)
• Azure OpenAI API key (for contextualization features)
• pip (Python package manager)

📦 Installation

1. Clone the repository (if applicable):

   git clone <repository-url>
   cd quiz-platform

2. Create a virtual environment (recommended):

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

⚙️ Configuration

Create a .env file in the project root directory with the following variables:

# Flask Configuration
SECRET_KEY=your-secret-key-here

# PostgreSQL Database
POSTGRES_URL=postgresql://user:password@host:port/database
# Example for Supabase:
# POSTGRES_URL=postgresql://postgres:[YOUR-PASSWORD]@db.[PROJECT-REF].supabase.co:5432/postgres?sslmode=require

# Azure OpenAI API
AZURE_OPENAI_API_KEY=your-azure-openai-api-key-here

Environment Variables Explained

• SECRET_KEY: A random secret key for Flask session management. Generate one using:

  import secrets
  print(secrets.token_hex(32))

• POSTGRES_URL: Connection string for your PostgreSQL database. The application uses this to store logs and survey responses.

• AZURE_OPENAI_API_KEY: API key for Azure OpenAI service, used for generating contextualized graph titles and axis labels.

Example .env file:

SECRET_KEY=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
POSTGRES_URL=postgresql://postgres:mypassword@localhost:5432/quizdb
AZURE_OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

🚀 Running the Application

1. Activate your virtual environment (if using one):

   source venv/bin/activate  # On Windows: venv\Scripts\activate

2. Initialize the database (first time only):

   python3 -c "from app import init_db; init_db()"

3. Run the Flask application:

   python3 app.py

   Or using Flask's development server:

   export FLASK_APP=app.py
   export FLASK_ENV=development
   flask run

4. Access the application:

   • Open your browser and navigate to http://localhost:5000 (or the port shown in the terminal)

📊 Data Analysis

The project includes Jupyter notebooks for data analysis and sentiment analysis.

Running the Analysis Notebook

1. Install Jupyter (if not already installed):

   pip install jupyter

2. Start Jupyter Notebook:

   jupyter notebook

3. Open data_analysis.ipynb:

   • The notebook contains comprehensive data analysis including:
     • Performance metrics (Phase 1, Phase 2, Phase 3)
     • Survey analysis
     • Sentiment analysis using RoBERTa model
   • Make sure the data files are in the data/ directory:
     • study_logs.csv
     • survey_responses.csv

Notebook Dependencies

The analysis notebook requires additional packages that are included in requirements.txt:

• transformers (for RoBERTa sentiment analysis)
• torch (PyTorch for the ML model)
• scipy, seaborn, matplotlib (for statistical analysis and visualization)
• tqdm (for progress bars)

📁 Project Structure

quiz-platform/
├── app.py                          # Main Flask application
├── viz_functions.py                 # Visualization helper functions
├── requirements.txt                 # Python dependencies
├── .env                             # Environment variables (create this)
├── README.md                        # This file
├── appendix.pdf                     # Supplementary material
│
├── data/                            # Data files
│   ├── study_logs.csv              # Study logs from database
│   ├── survey_responses.csv        # Survey responses
│   ├── user_ids.csv                # User identifiers
│   ├── open_responses_improved_users.csv      # Generated for sentiment analysis
│   └── open_responses_no_improvement_users.csv # Generated for sentiment analysis
│
├── templates/                       # HTML templates
│   ├── index.html
│   ├── consent.html
│   ├── question.html
│   ├── phase2_question.html
│   ├── survey_part1.html
│   ├── survey_part2.html
│   ├── survey_part3.html
│   └── ...
│
├── static/                          # Static files
│   ├── style.css
│   └── screenshots/
│
├── output/                          # Generated analysis plots
│   ├── transfer_4groups.png
│   ├── survey_cognitive_load.png
│   ├── avg_sentiment_scores.png
│   └── ...
│
└── data_analysis.ipynb             # Main analysis notebook

🔍 Features

• Multi-phase study design: Pretest (Phase 1), Learning phase (Phase 2), Posttest (Phase 3)
• Contextualization: AI-generated contextualized visualizations based on user interests
• Hints system: Optional hints during the learning phase
• Comprehensive logging: All user interactions are logged to PostgreSQL
• Survey integration: Multi-part survey with Likert scales and open-ended questions
• Data analysis: Statistical analysis and sentiment analysis of survey responses

🛠️ Development

Database Schema

The application uses two main tables:

1. logs: Stores all user actions and interactions

   • id, user_id, timestamp, action, details

2. survey_responses: Stores survey responses

   • id, user_id, timestamp, question_key, question_text, response, response_type

Exporting Data

To export data from PostgreSQL to CSV for analysis:

-- Export logs
COPY (SELECT * FROM logs ORDER BY timestamp) TO '/path/to/data/study_logs.csv' WITH CSV HEADER;

-- Export survey responses
COPY (SELECT * FROM survey_responses ORDER BY timestamp) TO '/path/to/data/survey_responses.csv' WITH CSV HEADER;

Or use a database client like pgAdmin or DBeaver to export the tables.

📄 Appendix

Supplementary material and additional details can be found in the Appendix.

📝 Notes

• The application uses Flask sessions for user state management
• All timestamps are stored in UTC
• The sentiment analysis uses the cardiffnlp/twitter-roberta-base-sentiment-latest model
• Generated plots are saved in the output/ directory