Metadata-Version: 2.4
Name: magnipy
Version: 1.0.0
Summary: A framework for computing the magnitude of a metric space.
License: BSD-3-Clause
License-File: LICENSE
Keywords: metric space magnitude
Author: LimbeckKat
Author-email: katharina.limbeck@helmholtz-munich.de
Requires-Python: >=3.10,<3.13
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: krypy (>=2.2.0,<3.0.0)
Requires-Dist: matplotlib (>=3.8.3,<4.0.0)
Requires-Dist: numexpr (>=2.10.1,<3.0.0)
Requires-Dist: scikit-learn (>=1.4.1,<2.0.0)
Requires-Dist: scipy (==1.13.0)
Requires-Dist: seaborn (>=0.13.2,<0.14.0)
Requires-Dist: torch (>=2.4.1,<3.0.0)
Project-URL: Repository, https://github.com/aidos-lab/magnipy
Description-Content-Type: text/markdown

# magnipy: Metric Space Magnitude Computations

This is a repository for computing the **_magnitude of a metric space_**, which encodes the **effective size, diversity, and geometry** of a metric space. Given a dataset or distance matrix, **_magnitude_** measures the **effective number of distinct points** in the space at a scale of dissimilarity between observations.
We introduce the following codebase to compute and compare the magnitude of metric spaces.

<p align="center">
<img src="assets/magnipy_logo.svg" alt="magnipy logo"  style="float: right; width: 200px; height: 200px; ">
</p>

## 🔍 Main Functionalities and Classes

### `Magnipy`: For in-depth magnitude computations on a single metric space.

The functionalities of `Magnipy` for an individual metric space include:  
- Computing the metric space's **distance matrix** based on a feature space (attributes), adjecencies between observations (structure), or both features and adjecencies (full).
- Calculating the **similarity matrix** from the distances
- Executing an **automated scale-finding** procedure to find suitable evaluation scales
- Computing the **magnitude weight** of each point across multiple distance scales
- Evaluating and plotting **magnitude functions** across varying distance scales
- Estimating magnitude dimension profiles and calculating the **magnitude dimension** to quantify **intrinsic dimensionality**

### `Diversipy`: For comparing magnitude (and thus diversity) across multiple datasets.

The functionalities of `Diversipy` for a list of spaces (that share the same distance metric) include: 
- Executing an **automated scale-finding** procedure and the determining a **common evaluation interval across datasets**
- Computing **magnitude functions** across varying distance scales
- Calculating **MagArea**, the area under a magnitude function, a multi-scale measure of the **intrinsic diversity** of a dataset
- Calculating **MagDiff**, the area between magnitude functions, to measure the **difference in diversity** between datasets

### `Graphipy`: For in-depth magnitude computations on a single metric graph.

The functionalities of `Graphipy` for an individual metric graph include:  
- Calculating the magnitude of a `networkx` graph by computing magnitude seperately for each disconnected subgraph
- Computing the metric based of features (attributes), graph structure (structure), or both features and graph structure (full).
- Other functionalities similar to `Magnipy`


## ⚙️ Dependencies

To get started,
1. Clone this repository locally into a directory of your choosing
2. Create and activate a new Python virtual environment

Our dependencies are managed using the [`poetry`](https://python-poetry.org) package manager. Using your activated virtual environment, run the following to install `poetry`:

```python
$ pip install poetry
```

With `poetry` installed, run the following command from the main directory to download the necessary dependencies:

```python
$ poetry install
```

## 📚 Tutorials

Tutorials demonstrating the main functionalities can be found under the `notebooks` folder.

The following tutorials demonstrate how to initialize and utiltize the corresponding classes:
- `magnipy_tutorial.ipynb`:  Using `Magnipy` for computing the magnitude of one metric space
- `diversipy_tutorial.ipynb`: Using `Diversipy` for comparing the magnitude of multiple metric spaces
- `graphipy_tutorial.ipynb`:  Using `Graphipy` for computing the magnitude of metric graphs

The following supplementary demos are also provided:
- `mode_dropping.ipynb`: Using `MagDiff` for detecting mode dropping / mode collapse


## 📝 Citation
Please consider citing our work!

```bibtex
@inproceedings{limbeck2025geometry,
  title         = {Geometry-aware Edge Pooling for Graph Neural Networks}, 
  author        = {Katharina Limbeck and Lydia Mezrag and Guy Wolf and Bastian Rieck},
  booktitle     = {Advances in Neural Information Processing Systems},
  volume        = {38},
  year          = {2025}
}

@inproceedings{limbeck2024metric,
  title         = {Metric Space Magnitude for Evaluating the Diversity of Latent Representations}, 
  author        = {Katharina Limbeck and Rayna Andreeva and Rik Sarkar and Bastian Rieck},
  booktitle     = {Advances in Neural Information Processing Systems},
  volume        = {37},
  year          = {2024}
}

@inproceedings{andreeva2023metric,
  title         = {Metric Space Magnitude and Generalisation in Neural Networks},
  author        = {Andreeva, Rayna and Limbeck, Katharina and Rieck, Bastian and Sarkar, Rik},
  year          = {2023},
  booktitle     = {Proceedings of 2nd Annual Workshop on Topology, Algebra, and Geometry in Machine Learning~(TAG-ML)},
  volume        = {221},
  pages         = {242--253}
}
```

