From 82f343a87615eabb96b1f519eb3c366fcc008dd3 Mon Sep 17 00:00:00 2001 From: Gard Spreemann Date: Tue, 22 Mar 2016 20:02:00 +0100 Subject: Some documentation --- README.md | 115 +++++++++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 103 insertions(+), 12 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 7bb5c22..71824d2 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ Introduction ===== -This package is a cleaned up subset of the hogdepodge of the Python -glue that I regularly use to massage data into and out of persistent +This package is a cleaned up subset of the hogdepodge of Python glue +that I regularly use to massage data into and out of persistent homology and other TDA computations. It does *not* compute anything itself, and exists primarily to marshal data into and out of the formats used by the excellent [DIPHA](https://github.com/DIPHA/dipha) @@ -20,29 +20,120 @@ following caveats: - The scripts were too messy to release as they were, and the cleaning up process means that this is now essentially untested software again. Beware. - -- There is nothing of substance here. This is just glue around - [DIPHA](https://github.com/DIPHA/dipha). - +- There is nothing of substance here. This is just glue around DIPHA. - I use Python as modern Perl, and my experience with it is limited to quickly manipulating data without too much thought for writing structured software. Beware. - - I make no attempt to accurately reflect the full capabilities of - [DIPHA](https://github.com/DIPHA/dipha). - + DIPHA. - Since Python will let you write `Interval("banana", 5)`, so will I, and you and your persistence generator "from banana to 5" can go solve problems down the road. Installation -===== +----- + +The scripts require NumPy and Matplotlib. If you want them to manage +running DIPHA as well, then you of course need working dipha and +mpirun executables. If the environment variables DIPHA and/or MPIRUN +are set, their values specify these executables. If not, those are +searched for in PATH. + +Todo/missing +---- -FIXME. +* Support for general filtered complexes (DIPHA's + `DIPHA_WEIGHTED_BOUNDARY_MATRIX`) to allow for non-flag + complexes. This has high priority, and should be added soon. +* More flexible plotting. Use ===== -FIXME. +I primarily use this scripts to convert to and from DIPHA's file +formats. The `DiphaRunner` class is available for those who would like +to avoid manually running DIPHA. + +I am not aiming for great performance, efficiency or generality with +these scripts. If you you want either, you are better off writing the +DIPHA files yourself. The scripts are intended to be easy to use. + + +Examples +----- + +### Saving a complete weighted graph in DIPHA's format + +This is as simple as + + import phstuff.diphawrapper as dipha + import numpy as np + + weights = np.random.uniform(0, 1, (100, 100)) # The graph. + dipha.save_weight_matrix("weights.dipha", weights) + +DIPHA can now be run on "weights.dipha". + +### Loading a DIPHA barcode file + +To load a dimension-`1` persistence diagram DIPHA stored in +"out.dipha", do: + + import phstuff.diphawrapper as dipha + + barcode = dipha.load_barcode("out.dipha") + for interval in barcode[1]: + print(interval) + +### Excluding edges/simplices above a certain weight + +If we want to exclude all edges with weights above some threshold in +the filtration, we can either use `save_edge_list` or +`save_masked_weight_matrix`. An example of the latter is shown below: + + import phstuff.diphawrapper as dipha + import numpy as np + import numpy.ma as ma + + weights = np.random.uniform(0, 1, (100, 100)) + masked = ma.masked_greater(weights, 0.5) # All weights above 0.5 are + # masked out and will not be + # present in the graph, + # effectively ending the + # filtration at 0.5. + dipha.save_masked_weight_matrix("weights.dipha", masked) + +For more information about masked arrays, see +[the NumPy documentation](https://docs.scipy.org/doc/numpy/reference/maskedarray.generic.html). Do +remember that the masked entries are the edges that will *not* be +present in the graph. + + +### Running DIPHA from Python + +If you prefer to control the entire computation from Python, these +scripts can generate the necessary temporary files and run DIPHA on +them. For this, the mpirun and dipha executables must be in the PATH +environment variable, or they must be specified through the MPIRUN and +DIPHA environment variables. + + weights = np.random.uniform(0, 1, (100, 100)) + dipharunner = dipha.DiphaRunner(2) # Compute up to 2-simplices. + dipharunner.weight_matrix(weights) + dipharunner.run() + + for interval in dipharunner.barcode[1]: + print(interval) + + fig = plt.figure() + ax = fig.add_subplot(1,1,1) + bc.plot(ax, dipharunner.barcode[1], weights.min(), weights.max()) + plt.show() + + + +### PH of an alpha complex made with CGAL + +TODO. -- cgit v1.2.3