Metadata-Version: 2.4
Name: MED-MAGMA
Version: 1.0.1
Summary: An implementation of the matrix elliptical distribution multi-axis graphical modelling algorithm.
Project-URL: Homepage, https://github.com/BaileyAndrew/MED-MAGMA
Project-URL: Bug Tracker, https://github.com/BaileyAndrew/MED-MAGMA/issues
Author-email: Bailey Andrew <sceba@leeds.ac.uk>
License: MIT License
        
        Copyright (c) 2026 BaileyAndrew
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.13
Requires-Dist: numpy>=2.3
Requires-Dist: scipy>=1.16
Description-Content-Type: text/markdown

# MED-MAGMA

The code to run MED-MAGMA is contained in `MED_MAGMA.py`.  Below is a minimal example of how to run it:

```{python}
from MED_MAGMA import quotient, EM_algorithm, sparse_quotient

# Let X be your dataset
X: np.ndarray

# Map it to the quotient space
# If X contains zeros, use `sparse_quotient` instead
Y = quotient(X)

# Run our algorithm; EM_results contains the learned graphs, magnitudes contains the learned "r" values if those are of interest
EM_results, magnitudes = EM_algorithm(Y, max_iter = 100, verbose=False, very_verbose=False, stop_tol=1e-7, regularization=0)
```

In the paper we mentioned briefly that one could turn the $\mathbf{z}^*$ estimation portion of our algorithm into a convex problem by using a simplex constraint rather than our geometric mean constraint (but that this would introduce bias into the algorithm that made it unsuitable).  If you wish to check this out for yourself, we have `MED_MAGMA_simplex.py` which has the same API as `MED_MAGMA.py`.  What you'll find is that it works for synthetic data, but on most real datasets it just learns an essentially constant matrix (which manifests from the aforementioned bias towards the simplex's corners - which dominates when signal-to-noise is lower).

## Package

This algorithm is available on PyPI [https://pypi.org/project/MED-MAGMA/1.0.0/](https://pypi.org/project/MED-MAGMA/1.0.0/).

### Dependencies

This code was written in Python 3.13 with NumPy 2.3 and SciPy 1.16.

The exact environment used to run the paper's experiments is given in `environment.yaml`, but to just run our algorithm only Python, NumPy, and SciPy are required.  (`MED_MAGAM_simplex` requires cvxpy as well).

## Paper

The figures for the paper are generated in the following:

* Figure 1 (Tail Dependence): `median-data-experiment.ipynb`
* Figure 2 (Synthetic Validation): `synthetic-experiments-paper.ipynb`
* Figure 3 (Real Validation): `all-real-data-all.ipynb`
* Figure 4 (UMAP): `median-data-experiment.ipynb`
* Figure 5 (Supplementary, Synthetic Validation): `synthetic-experiments-paper.ipynb`
* Figure 6 (Supplementary, Effect of Sparsity): `synthetic-experiments-paper.ipynb`

All further empirical values given in the paper are from `median-data-experiment.ipynb`, except for robustness using `Robin`; this is computed in `robin-on-median.rmd` (an R markdown file).

The conda environment used to generate these results is given in `environment.yaml`.