PECAN: Persistent Condensation

This repository contains the code for our work on Time-Inhomogeneous Diffusion Geometry and Topology. If you use this code, please consider citing our paper:

@article{Huguet23a,
  title         = {Time-Inhomogeneous Diffusion Geometry and Topology},
  author        = {Huguet, Guillaume and Tong, Alexander and Rieck, Bastian and Huang, Jessie and Kuchroo, Manik and Hirn, Matthew and Wolf, Guy and Krishnaswamy, Smita},
  journal       = {SIAM Journal on Mathematics of Data Science},
  year          = 2023,
  volume        = 5,
  number        = 2,
  pages         = {346--372},
  doi           = {10.1137/21M1462945},
  primaryclass  = {cs.LG},
  archiveprefix = {arXiv},
  eprint        = {2203.14860},
}

Installing the package

The recommended way of installing the package entails using poetry for Python. After cloning this repository, everything can be set up using the following command, with $ indicating that the command is to be executed in your terminal:

$ poetry install 

Using the package

The simplest way of using the package uses a shell spawned by poetry:

$ poetry shell

You should now be able to call the main scripts of the package.

Running the algorithm

To run the algorithm on a 'double annulus' data set, use the following command:

$ python condensation.py -n 256 -d double_annulus -o double_annulus.npz

This will create a file double_annulus.npz containing information about the condensation process. By changing the parameter -n, you can control the number of points that are to be used.

Visualising the results

To visualise the results, you can use either visualise_diffusion_homology.py or visualise_persistent_homology.py, depending on what type of features you are interested in. Both of these scripts accept a file generated by condensation.py as an input. For instance, to show the diffusion homology of the 'double annulus' data set over time, use the following command:

$ python visualise_diffusion_homology.py double_annulus.npz

Note that all visualisations are meant for research purposes only and are subject to change as the project progresses.

Using the Rivet callback

The code now supports bifiltrations. To make use of this functionality, you need to install rivet_console. If you are on Mac OS X, you can use HomeBrew for this purpose:

$ brew tap BorgwardtLab/mlcb
$ brew install rivet

Regardless of the installation method, make sure that you tell poetry that additional dependencies are present:

$ poetry update

This ensures that the Python 'wrapper' for rivet_console is installed.

Using Oineus bindings

Oineus is a fast C++ library for calculating persistent homology. It comes with Python bindings, which we have wrapped in py-oineus, an experimental package. The module requires a recent C++ compiler (supporting C++17) as well as support for Threading Building Blocks. If you install those library, for instance via brew install tbb, you can add the oineus Python bindings to the project like this:

$ poetry shell
$ pip install git+ssh://git@github.com/aidos-lab/py-oineus

To test the integration, run python pecan/oineus_integration.py in the proper virtual environment.