API Outline#

In HomCloud, Python API is integrated into one module, homcloud.interface module. If you want to use the API from python, first you sholud import the module as follows:

import homcloud.interface as hc

To learn HomCloud’s Python API, you first see homcloud.interface.PDList class and homcloud.interface.PD class. You can get access to all of HomCloud’s functionality through these two classes.

`homcloud.interface.PDList`#

This class represents the list of 0, 1, .., n-th persistence diagrams from a single input. In HomCloud, all of these diagrams are stored into one file, a file with .pdmg. You can use .idiagram extension for backward compatibility, but some HomCloud’s functionaties are not available with .idiagram file. You can compute the list of PDs by the folloiwng static methods.

homcloud.interface.PDList.from_alpha_filtration() for pointclouds
homcloud.interface.PDList.from_bitmap_levelset() for grayscale bitmap data
homcloud.interface.PDList.from_bitmap_levelset() with homcloud.interface.distance_transform() for binary bitmap data
homcloud.interface.PDList.from_rips_filtration() for a distance matrix
homcloud.interface.PDList.from_boundary_information() for a boundary map and levels.

These methods computes a list of PDs, and return a homcloud.interface.PDList object. You can store the data into a file by using save_to parameter.

You can create a homcloud.interface.PDList object from the file by using the constructor of the class.

You can get the q-th PD object by homcloud.interface.PDList.dth_diagram(). This method returns homcloud.interface.PD object.

`homcloud.interface.PD`#

This class represents a q-th PD and the object has all information about the PD. You can get access to the birth times ,death times and some other information from the object. For example, the following methods are available.

Many other methods are available for your analysis.

You can also compute a histogram by one of the following methods

On one hand, homcloud.interface.PD.histogram() is a straightforwad way to compute a histogram. Only you should do is to give the range and the number of bins and you get a homcloud.interface.Histogram object. On the other hand, homcloud.interface.HistoSpec.pd_histogram() is more indirect way. You should create a homcloud.interface.HistoSpec object and call homcloud.interface.HistoSpec.pd_histogram() with a PD object. homcloud.interface.HistoSpec will be useful if you need to compute many hitograms with the same binsize.

You can plot the histogram by homcloud.interface.Histogram.plot(). In this method, matplotlib is used, therefore you can save the figure by matplotlib.pyplot.savefig and you can popup a window by matplotlib.pyplot.show. If you use jupyter notebook, the figure is automatically shown in the notebook.

Other classes#

In HomCloud’s python API, there are many other classes and methods.

If you want to construct a vector by persitence image method [1] [2], to apply machine learning, please use homcloud.interface.PIVectorizeSpec.

If you want to compute an optimal volume (the optimal volume shows the geometric origin of each birth-death pair, please see https://epubs.siam.org/doi/abs/10.1137/17M1159439 for the detail), please use homcloud.interface.Pair.optimal_volume(). This method returns an object of homcloud.interface.OptimalVolume.