recommetal 🤘: Doc2Vec Analysis of Metal Album Reviews

Project Overview

recommetal is a Python project designed to analyze a corpus of metal album reviews using Doc2Vec (Document to Vector) embeddings. The primary goal is to learn dense numerical representations (vectors) for bands, albums, and words, allowing for quantitative analysis of semantic similarity and characteristic features.

"You shall know a word by the company it keeps" - J. R. Firth

The project enables advanced queries such as:

• Finding bands or albums with similar review content.
• Identifying the words most characteristic of a specific band's reviews.
• Visualizing the embedding space of top-rated bands using techniques like t-SNE.

The core functionality is contained within the Doc2VecAnalyzer class, which manages the entire machine learning pipeline from data loading to visualization.

---

Prerequisites

To run this project, you'll need Python and the packages defined in the pyproject.toml file.

1. Python: Python 3.9 or newer is required.
2. Data File: This script expects a CSV file named reviews.csv in the project root directory. The file should have columns corresponding to band name, album name, review rating, vote count, and the review text.

---

Installation and Setup

1. Clone the Repository

git clone https://github.com/edwardcjohnson/recommetal
cd recommetal

2. Create a Virtual Environment

It's highly recommended to use a virtual environment to manage dependencies.

python -m venv venv
source venv/bin/activate  # On Windows, use: .\venv\Scripts\activate

3. Install Dependencies

Install all required packages listed in pyproject.toml using pip:

pip install -e .

4. Obtain Data

Place your review data file, named reviews.csv, into the root of the project directory.

---

Usage

The entire analysis workflow is executed by running the single script located at code/explore/doc2vec_analysis.py. This script contains the Doc2VecAnalyzer class and a main execution block (if __name__ == '__main__':) that demonstrates the full process.

Running the Analysis

python code/explore/doc2vec_analysis.py

Output

When the script runs, it performs the following steps:

1. Data Loading: Reads reviews.csv and preprocesses the text (tokenization, stopword removal).
2. Training: Trains the Doc2Vec model, learning 150-dimensional vectors for bands and words.
3. Inference: Prints similarity results to the console (e.g., bands similar to 'Opeth', words characterizing 'Agalloch').
4. Visualization: Generates 2D embedding plots for the top 100 highest-rated bands.

The resulting image files are saved in a new directory named plots/ within the project root:

• plots/top_bands_tsne.png
• plots/top_albums_spectral.png

---

Code Structure

File/Directory	Description
code/explore/doc2vec_analysis.py	The main executable script. Contains the Doc2VecAnalyzer class, which encapsulates the entire NLP pipeline.
pyproject.toml	The standard configuration file defining project metadata and all required Python dependencies.
README.md	This file.
plots/	Directory where generated t-SNE and Spectral Embedding visualization images are saved.

---

Customization

The script is highly customizable by editing the parameters within the Doc2VecAnalyzer's instantiation and method calls in the main execution block of code/explore/doc2vec_analysis.py.

Parameter	Location	Description
vector_size	analyzer = Doc2VecAnalyzer(...)	Dimensionality of the learned vectors.
epochs	analyzer.train_model(epochs=30)	Number of passes over the training data.
QUERY	In the if __name__ block	SQL-like query to select data for visualization (e.g., 'rating > 8 and votes > 1000').
perplexity	analyzer.plot_embeddings(...)	Key parameter for t-SNE, affecting how local vs. global structures are preserved.