Some documentation

1 files changed, 103 insertions, 12 deletions

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.