Getting Started with QPERA¶

This guide will help you set up the QPERA framework, download the necessary datasets, and run your first experiments.

Prerequisites¶

Python 3.9+
Conda or Miniconda
Git
Kaggle account (for dataset downloads)

🚀 Quick Start (Recommended)¶

This is the fastest way to get started. The quickstart command automates the entire setup, download, and execution process.

Clone the repository:

git clone https://github.com/PUT-RecSys-Research/qpera-thesis.git
cd qpera-thesis

Configure Kaggle API: This project requires the Kaggle API for downloading datasets.
- Download your kaggle.json API token from your Kaggle account page.
- For automated setup instructions, run:
```
kaggle-autoconfig
```
Run the Quick Start command: This command will install the environment, download all datasets, and run the full experiment suite.
```
make quickstart
```
After completion, you can view the results in the MLflow UI.

🛠️ Step-by-Step Installation¶

For more control over the setup process, follow these steps.

1. Clone the Repository¶

git clone https://github.com/PUT-RecSys-Research/qpera-thesis.git
cd qpera-thesis

2. Configure Kaggle API¶

Download your Kaggle API key (kaggle.json) and place it in ~/.kaggle/. For detailed instructions, run:

make kaggle-setup-help

- Ensure your kaggle.json file is placed correctly.

3. Environment and Dependencies¶

# Create the conda environment from the environment.yml file
make install

# Activate the new environment
conda activate ppera-env

# Install the project package in editable mode
make setup

4. Verify Installation¶

# Run this command to ensure the package is installed correctly
make check-env

5. Download Datasets¶

# Download all datasets required for the experiments
make download-datasets

For more details, see the Datasets Guide.

🔬 Running Experiments¶

Once the setup is complete, you can run experiments.

Run the Full Suite¶

To execute all defined experiments across all datasets (Note: this will take a significant amount of time):

make run-all

📊 Viewing Results¶

The framework uses MLflow to track experiments.

Start the MLflow UI:
```
make run-mlflow
```
Open your browser: Navigate to http://127.0.0.1:8080 to view experiment runs, parameters, and metrics.

🗺️ What's Next?¶

Datasets Guide: Learn more about the datasets used in this project.
Experiments Guide: See how to configure and customize experiment runs.
Architecture Overview: Understand the project's code structure.

❓ Support & Questions¶

If you encounter any issues or have questions about the research, please feel free to:

Open an Issue: For bugs or unexpected behavior, please open a new issue.
Start a Discussion: For general questions or ideas, start a discussion.
Contact the Authors: You can also reach out to the authors listed in the main README.md.