t-vMF

This project implements the t-vMF (truncated von Mises-Fisher) similarity function as described in Takumi Kobayashi's paper. The paper introduced t-vMF similarity as a regularization technique for intra-class feature distribution in machine learning. I hope to explore the utility of t-vMF for other applications, such as text data (ie. comparing BERT vectors).

References

• t-vMF Similarity For Regularizing Intra-Class Feature Distribution
• https://github.com/tk1980/tvMF

Setup and Installation

Prerequisites

• Python 3.7 or higher
• pip (Python package installer)

Setting up a Virtual Environment

1. Clone the repository:

   git clone <repository-url>
   cd t-vMF

2. Create a virtual environment:

   python -m venv venv

3. Activate the virtual environment:

   On Linux/macOS:

   source venv/bin/activate

   On Windows:

   venv\Scripts\activate

4. Install required packages:

   pip install -r requirements.txt

Running the Demo

1. Start Jupyter Notebook:

   jupyter notebook

2. Open and run the demo:

   • Navigate to demo.ipynb in the Jupyter interface
   • Run all cells to see the t-vMF similarity implementation and visualization

Deactivating the Virtual Environment

When you're done working with the project:

deactivate

Implementation Details

The main implementation (from the paper) includes:

• tvMF_similarity(w, x, k): Core function that computes t-vMF similarity

  • w: classifier weight vector
  • x: input feature vector
  • k: kappa parameter (controls concentration)

• Visualization: 2D polar plots showing how t-vMF similarity varies with different kappa values

• Examples: Demonstration with various input vectors and kappa parameters

Mathematical Background

The t-vMF similarity is computed as:

φ = (1 + cosine) / (1 + κ(1 - cosine)) - 1

Where:

• cosine = dot(normalize(x), normalize(w))
• κ (kappa) controls the concentration parameter
• Higher κ values create sharper concentration around the classifier weight vector