Write quickstart guide for documentation

[Pseudomanifold]

Just covering the basics for new users: suppose you don't care about topology at all, what's the smallest thing you can add to your code to make it 'topology-aware?'

[daresut]

imo, a new user would like to see a detailed overview of I/O from functions in the library. I found this from the source code:

    Dense tensor representation of `x`. The output is best
    understood by considering some examples: given a batch
    obtained from :class:`VietorisRipsComplex`, our tensor
    will have shape `(B, N, 3)`. `B` is the batch size and
    `N` is the sum of maximum lengths of diagrams relative
    to this batch. Each entry will consist of a creator, a
    destroyer, and a dimension. Dummy entries, used to pad
    the batch, can be detected as `torch.nan`.

This is good, but it would be handy to have a binary image of blobs and maybe an output so users can get an intuitive understanding of the library.

[Pseudomanifold]

That's a great idea! Do you know whether this can be added in the code itself and then referenced from some other place in the docs? I'd love to to add something like this but also want to prevent code duplication.

[daresut]

Maybe it could be another demo? Like a notebook. I've been experimenting with the CubicalComplex function using inputs like this:



I expect the number of 0 dim topological features to be 1, 2, and 10 (top to bottom respectively) but the outputs from the library were quite different. So perhaps a demo with toy inputs would be handy for new users. I definitely can help as I am experimenting with this now :).

[Pseudomanifold]

Thanks! Can you add some example code as well and the actual output if you have that handy?

[daresut]

import os
import json
import glob
import torch
import numpy as np
import matplotlib.pyplot as plt
from PIL import Image
from skimage.filters import gaussian
from skimage.transform import resize, rescale
from torch_topological.nn import CubicalComplex

### Toy experiments using structured binary inputs (b/w images) for PyTorch-Topological. D.S. July 2023

def binarize(im, t=0.5):
    im = im/np.max(im) # normalize
    im = im > t
    im = im.astype(float)
    return im

def main():
    topo_analyzer = CubicalComplex()
    dataDir = '/local-scratch2/darren/datasets/toy'

    ### iterate over test images
    for i in range(2, 6):
        path = os.path.join(dataDir, 'test{}.png'.format(i))
        test_im = Image.open(path)
        
        test_im = np.array(test_im).astype(float)
        small_im = rescale(test_im, 0.5)
        smaller_im = rescale(test_im, 0.25)

        ### run on original resolution
        test_im = test_im[:,:,0]
        test_im = binarize(test_im) 
        test_im = torch.tensor(test_im)

        y = topo_analyzer(test_im)
        print('the number of 0-dim features in the original image is {}'.format(len(y[0][0])))

        ### run on the small image
        small_im = small_im[:,:,0]
        small_im = binarize(small_im)
        small_im = torch.tensor(small_im)

        s = topo_analyzer(small_im)
        print('the number of 0-dim features in the downscaled image is {}'.format(len(s[0][0])))

        ### run on the smaller image
        smaller_im = smaller_im[:,:,0]
        smaller_im = binarize(smaller_im)
        smaller_im = torch.tensor(smaller_im)

        z = topo_analyzer(smaller_im)
        print('the number of 0-dim features in the downscaled image is {}'.format(len(z[0][0])))

        ### Visualize

        plt.subplot(1,3,1)
        plt.imshow(test_im)
        plt.title('original image')
        plt.subplot(1,3,2)
        plt.imshow(small_im)
        plt.title('1/2 resolution')
        plt.subplot(1,3,3)
        plt.imshow(smaller_im)
        plt.title('1/4 resolution')
        plt.show()

if __name__ == "__main__":
    main()

viz of input:

outputs:

I ran this script on a few toy images and there seemed to be a correlation between resolution and detected 0 dim topological features.

[Pseudomanifold]

Thanks! I'll look into this.