scikit-tda / cechmate

Custom filtration constructors for Python

Scikit-TDA is a home for Topological Data Analysis Python libraries intended for non-topologists.

This project aims to provide a curated library of TDA Python tools that are widely usable and easily approachable. It is structured so that each package can stand alone or be used as part of the scikit-tda bundle.

Documentation

For complete documentation please checkout docs.scikit-tda.org.

Contact

If you would like to contribute, please reach out to us on github by starting a discussion topic, creating an issue, or reaching out on twitter.

Setup

To install all these libraries

    pip install scikit-tda

Citations

If you would like to cite Scikit-TDA, please use the following citation/bibtex

Saul, Nathaniel and Tralie, Chris. (2019). Scikit-TDA: Topological Data Analysis for Python. Zenodo. http://doi.org/10.5281/zenodo.2533369

@misc{scikittda2019,
  author       = {Nathaniel Saul, Chris Tralie},
  title        = {Scikit-TDA: Topological Data Analysis for Python},
  year         = 2019,
  doi          = {10.5281/zenodo.2533369},
  url          = {https://doi.org/10.5281/zenodo.2533369}
}

License

This package is licensed with the MIT license.

Contributing

Contributions are more than welcome! There are lots of opportunities for potential projects, so please get in touch if you would like to help out. Everything from code to notebooks to examples and documentation are all equally valuable so please don't feel you can't contribute. To contribute please fork the project make your changes and submit a pull request. We will do our best to work through any issues with you and get your code merged into the main branch.

cechmate's Issues

Add weighted filtrations

Related to #15, but I want to make sure it's numerically stable since squares are involved

Nonsimplicial complexes

I'd like to add an argument "simplicial" to cm.phat_diagrams which would default to True and would check that the filtration was indeed a simplicial complex, not just a CW(?)-complex. If one wanted to use a CW(?)-complex, they could pass simplicial=False and proceed. I was thinking the check would also coerce a "non-simplicial" filtration to one by remembering only the first time a simplex was added, so if it is "added again" we are effectively just saying "ok its already present at time t so keep going."

I am concerned that checking every time may not make sense if the user knows that they have a simplicial complex and then the check would slow things down and not be useful. So I'm not sure whether it should be something like assert_simplicial which would default to False, and then passing True would do the check and coerce to a simplicial filtration. Does anyone have any thoughts?

The following example exhibits the nonsimplicial (CW?) behavior:

>>> filtration = [('a',0),('b',0),('ab',1),('ab',2),('ab',3)]
>>> cm.phat_diagrams(filtration, show_inf=True, verbose=False)
[array([[ 0., 1.], [ 0., inf]]), array([[ 2., inf], [ 3., inf]])]

This makes sense if each instance of the additional 'ab' edge is a new edge, because we have two vertices and three edges between them, so past t=3, we would expect two generators for the 1st homology. 

I want to call it a CW-complex but that doesn't seem quite right because cechmate does check that lower dimensional things are added before higher dimensional things, so it doesn't allow for a cellular decomposition of a 2-sphere into a 0-cell and a 2-cell (without a 1-cell). For example:

>>> filtration = [('a',0),('aaa',0)]
>>> cm.phat_diagrams(filtration, show_inf=True, verbose=False)
Traceback (most recent call last):
    ...
Exception: Error: Not a proper filtration: ['a' 'a' 'a'] added before ('a', 'a')

It also gives funky results when you try to construct $S^1$ with a 0-cell and a 1-cell.

>>> filtration = [('a',0),('aa',0)]
>>> cm.phat_diagrams(filtration, show_inf=True, verbose=False)
[]

which makes sense on the level of ∂(aa) = a-a = 0, but not on the level of the actual topology. In any case, I don't think the first example is a simplicial complex because a simplicial complex on {a,b} should be a subset of 2^{a,b}, not a sub-multiset. (I'm just saying this so that you can correct me if I'm misunderstanding something.)

However, the structure of S2 can be built up in a somewhat interesting way by:

>>> filtration = [('a',0),('b',0),('c',0),('ab',1),('bc',2),('ac',3),('abc',4),('abc',5)]
>>> cm.phat_diagrams(filtration, show_inf=True, verbose=False)
[array([[ 0.,  1.],
       [ 0.,  2.],
       [ 0., inf]]), array([[3, 4]]), array([[ 5., inf]])]

I'm not sure if what I described was the intended behavior or not, but I do see some use cases for it, so I think it should be kept for added flexibility in the complexes which one can construct.

Question in Basic Usage

Hi there,

I have a question regarding the Basic Usage in the Documentation.

In the example of cech diagram, what is the purpose of the "times two" operation? See attached:

dgmscech = cech.diagrams() * 2

BTW, there seems to be a typo in the doc, all the max_dim=1 should be maxdim=1 to prevent error.

Thanks!

Error with Alpha filtration

Hey,
First of all, thanks for a great package. I find all of the scikit-tda packages really useful.
I'm trying to compute Alpha filtration of a 3-dimensional data (attached as a text file) and I get the following error(but return an empty persistence diagram)
I couldn't find enough resources online as to why this can be the case.
Any help on this would be greatly appreciated.

Doing spatial.Delaunay triangulation...
Finished spatial.Delaunay triangulation (Elapsed Time 0.00938)
Building alpha filtration...
Finished building alpha filtration (Elapsed Time 4.01)
Constructing boundary matrix...
Error: Not a proper filtration: [107 111 207] added before (107, 111)
Computing persistence pairs...
Finished computing persistence pairs (Elapsed Time 9.16e-05)

points.txt

Unify Ripser.py and Cechmate interfaces

As an extension of #6, we should also update the interfaces to abide by fit_transform

Currently, the Ripser.py Rips object uses fit_transform to construct the diagrams. Cechmate uses build to construct the filtration and diagrams to build the diagrams.

We should convert cechmate so that fit builds the simplices and transform constructs the diagrams.

Change `max_dim` to `maxdim`

Ripser.py uses the keyword maxdim while cechmate uses max_dim. We should standardize this across both projects. Since Ripser.py has a userbase already, I vote we change cechmate.

Why the main loop in alpha.py starts from maxdim + 2?

I was going through the code alpha.py. At line 65, the loop starts from maxdim+2. However, on line 47, it has been set to X.shape[1]-1. So my questions --

1. Why line 65 does not start from maxdim? How would you get a d+2 dimensional simplex in a d dimensional space?
2. As maxdim has been set to X.shape[1]-1 already, then why does line 65 start from maxdim+2 instead of maxdim+1?

Thanks.

A problem about installing

Alpha Complex Filtraton

Filtration values of the simplices in the Alpha complex can be much larger than they should be. I found this issue when experimenting with Alpha complexes built on points from a uniform normal distribution in 2D.
To reproduce this problem, you can call the following code a few times and see that there will be filtration values much larger than 10, which is basically impossible for the given distribution.
I also double checked that the referenced triangles actually have a much smaller circumradius than what is given in the Alpha complex. It seems to happen for those triangles that already have quite a large filtration value.

import numpy as np
from cechmate.filtrations import Alpha
points = np.random.randn(20, 2)
simplices, filtration = zip(*Alpha().build(points))
max(filtration)

Here an example data set that would gives a maximum filtration value of 11.18, namely for the triangle (1, 4, 10) and the line (4, 10). The line refers to points (-0.66838721, -2.21357309) and (-0.68879532, 1.36314908), so the actual filtration value should be 1.800.

points = np.array(
      [[ 0.01743489,  0.83907818],
       [-0.57518843,  0.46536324],
       [-0.19659281, -0.66731467],
       [ 1.52911009, -0.68218385],
       [-0.66838721, -2.21357309],
       [ 1.14180137,  0.79701124],
       [-0.05349503, -2.25566765],
       [-0.27223817,  0.77621451],
       [ 0.38597224,  1.15861246],
       [-0.29454972,  1.71746955],
       [-0.68879532,  1.36314908],
       [-0.47834989, -1.57854915],
       [ 0.94477495, -0.38586968],
       [-0.04377718, -0.84981483],
       [-0.03082609, -1.63861901],
       [ 1.73579262, -0.02458939],
       [ 0.50910058,  0.66446628],
       [ 1.88017434,  1.66114513],
       [ 1.47186944, -0.68486166]])

Installation on ArchLinux

I ran pip3 install cechmate and got the following error.

pip3 install cechmate
Defaulting to user installation because normal site-packages is not writeable
Collecting cechmate
  Using cached cechmate-0.1.0-py3-none-any.whl (23 kB)
Requirement already satisfied: matplotlib in /usr/lib/python3.10/site-packages (from cechmate) (3.5.1)
Requirement already satisfied: persim in ./.local/lib/python3.10/site-packages (from cechmate) (0.3.1)
Requirement already satisfied: scipy in /usr/lib/python3.10/site-packages (from cechmate) (1.7.3)
Requirement already satisfied: numpy in /usr/lib/python3.10/site-packages (from cechmate) (1.21.5)
Collecting phat==1.5.0a0
  Using cached phat-1.5.0a.tar.gz (4.7 MB)
  WARNING: Requested phat==1.5.0a0 from https://files.pythonhosted.org/packages/43/82/c14de81dc2953a71a060f72f2bc34c41996307956b162751f2a47e2c78f7/phat-1.5.0a.tar.gz#sha256=51e7fe5e05adf5c7e0895765572fff05b979731234251f13011610d71d4980ab (from cechmate), but installing version 1.5.0
WARNING: Discarding https://files.pythonhosted.org/packages/43/82/c14de81dc2953a71a060f72f2bc34c41996307956b162751f2a47e2c78f7/phat-1.5.0a.tar.gz#sha256=51e7fe5e05adf5c7e0895765572fff05b979731234251f13011610d71d4980ab (from https://pypi.org/simple/phat/). Requested phat==1.5.0a0 from https://files.pythonhosted.org/packages/43/82/c14de81dc2953a71a060f72f2bc34c41996307956b162751f2a47e2c78f7/phat-1.5.0a.tar.gz#sha256=51e7fe5e05adf5c7e0895765572fff05b979731234251f13011610d71d4980ab (from cechmate) has different version in metadata: '1.5.0'
Collecting cechmate
  Using cached cechmate-0.0.10-py3-none-any.whl (23 kB)
  Using cached cechmate-0.0.9-py3-none-any.whl (24 kB)
  Using cached cechmate-0.0.8-py3-none-any.whl (20 kB)
  Using cached cechmate-0.0.7-py3-none-any.whl (12 kB)
  Using cached cechmate-0.0.6-py3-none-any.whl (6.2 kB)
  Using cached cechmate-0.0.5-py3-none-any.whl (6.1 kB)
  Using cached cechmate-0.0.4-py3-none-any.whl (8.2 kB)
  Using cached cechmate-0.0.3-py3-none-any.whl (7.9 kB)
ERROR: Cannot install cechmate==0.0.10, cechmate==0.0.3, cechmate==0.0.4, cechmate==0.0.5, cechmate==0.0.6, cechmate==0.0.7, cechmate==0.0.8, cechmate==0.0.9 and cechmate==0.1.0 because these package versions have conflicting dependencies.

The conflict is caused by:
    cechmate 0.1.0 depends on phat==1.5.0a0
    cechmate 0.0.10 depends on phat
    cechmate 0.0.9 depends on phat
    cechmate 0.0.8 depends on phat
    cechmate 0.0.7 depends on phat
    cechmate 0.0.6 depends on phat
    cechmate 0.0.5 depends on phat
    cechmate 0.0.4 depends on phat
    cechmate 0.0.3 depends on phat

To fix this you could try to:
1. loosen the range of package versions you've specified
2. remove package versions to allow pip attempt to solve the dependency conflict

ERROR: ResolutionImpossible: for help visit https://pip.pypa.io/en/latest/user_guide/#fixing-conflicting-dependencies