Interspace

A comprehensive collection of distance and similarity functions for vectors, sequences, and distributions. Designed for machine learning, data science, and scientific computing applications.

Features

• Vector Distances: Euclidean, Manhattan, Minkowski, Chebyshev, Cosine, Mahalanobis
• Geographic Distances: Haversine (great-circle distance)
• Sequence Distances: Hamming, Jaccard, Dice, Matching, Overlap
• Distribution Distances: Canberra, Bray-Curtis, Squared Chord, Correlation
• Type hints for better IDE support
• Comprehensive documentation with examples
• 100% test coverage

Installation

From PyPI

pip install interspace

From Source

git clone https://github.com/rehanguha/interspace.git
cd interspace
pip install -e .

Development Installation

pip install -e ".[dev]"

Quick Start

import interspace

# Euclidean distance
print(interspace.euclidean([1, 2, 3], [4, 5, 6]))
# 5.196152422706632

# Manhattan distance
print(interspace.manhattan([1, 2, 3], [4, 5, 6]))
# 9.0

# Cosine similarity
print(interspace.cosine_similarity([1, 0, 0], [0, 1, 0]))
# 0.0

# Haversine distance (in meters)
print(interspace.haversine((42.5170365, 15.2778599), (51.5073219, -0.1276474)))
# 1231910.73... (Zagreb to London)

Available Functions

Vector Distances

Geographic Distances

Sequence/Set Distances

Distribution Distances

Usage Examples

Basic Distances

import interspace

# Euclidean distance
result = interspace.euclidean([1, 2, 3], [4, 5, 6])
# 5.196152422706632

# Minkowski with different p values
interspace.minkowski([1, 2], [4, 6], p=1)  # Manhattan: 7.0
interspace.minkowski([1, 2], [4, 6], p=2)  # Euclidean: 5.0
interspace.minkowski([1, 2], [4, 6], p=3)  # ~5.04

# Chebyshev (maximum) distance
interspace.chebyshev_distance([1, 2, 3], [4, 5, 6])
# 3.0

Cosine Similarity & Distance

# Orthogonal vectors
interspace.cosine_similarity([1, 0], [0, 1])  # 0.0
interspace.cosine_distance([1, 0], [0, 1])    # 1.0

# Identical vectors
interspace.cosine_similarity([1, 1], [1, 1])  # 1.0
interspace.cosine_distance([1, 1], [1, 1])    # 0.0

# Opposite vectors
interspace.cosine_similarity([1, 0], [-1, 0])  # -1.0
interspace.cosine_distance([1, 0], [-1, 0])    # 2.0

Geographic Distance (Haversine)

# Distance between two cities (in meters)
zagreb = (45.8150, 15.9819)
london = (51.5074, -0.1278)
distance = interspace.haversine(zagreb, london)
# ~1230000 meters (1230 km)

# Use a different radius (e.g., Mars)
mars_distance = interspace.haversine((0, 0), (45, 90), R=3389000)

Hamming Distance

# For integers (bitwise)
interspace.hamming(0b1010, 0b0011)  # 2

# For strings
interspace.hamming("karolin", "kathrin")  # 3

# For arrays
interspace.hamming([1, 2, 3, 4], [1, 0, 3, 5])  # 2

Set-based Distances

# Jaccard distance
interspace.jaccard_distance([1, 2, 3], [2, 3, 4])  # 0.5

# Dice distance
interspace.dice_distance([1, 2, 3], [2, 3, 4])  # 0.4

# Overlap distance
interspace.overlap_distance([1, 2, 3], [2, 3, 4])  # 0.5

Distribution Distances

# Canberra distance
interspace.canberra_distance([1, 2, 3], [2, 2, 4])

# Bray-Curtis distance
interspace.braycurtis_distance([1, 2, 3], [2, 2, 4])

# Correlation distance
interspace.correlation_distance([1, 2, 3], [3, 2, 1])  # 2.0

Mahalanobis Distance

import numpy as np

# Inverse covariance matrix
VI = np.array([[1, 0.5], [0.5, 1]])

# Distance between two points
interspace.mahalanobis([0, 0], [1, 1], VI)

API Reference

For detailed API documentation, see the API Reference or use Python's help:

import interspace
help(interspace.euclidean)

Development

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=interspace --cov-report=html

Code Quality

# Format code
black interspace/

# Lint
ruff check interspace/

# Type check
mypy interspace/

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Changelog

See CHANGELOG.md for version history.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Rehan Guha

• Email: rehanguha29@gmail.com
• GitHub: @rehanguha

Acknowledgments

Inspired by scipy.spatial.distance and designed for simplicity and ease of use.