Progress on documentation; in particular, fleshed out a better organi…

…zation in the subpage structure. Content still needs a lot of cleanup to fit this organization.
rivetTDA · mlwright84 · Aug 11, 2018 · Jul 4, 2018 · Jul 6, 2018 · Jul 6, 2018
commit be7d3ae8b90f1de2f54a18157c38f01ebd6a6baf
diff --git a/docs/FAQ.rst b/docs/FAQ.rst
@@ -1,13 +1,6 @@
 Frequently Asked Questions
 ==========================
 
-
-Can RIVET handle arbitrary bifiltrations?
------------------------------------------
-
-Yes. The most flexible option for RIVET input is the :ref:`firep` input type.
-
-
 How large a bifiltration can RIVET handle?
 ------------------------------------------
 

diff --git a/docs/about.rst b/docs/about.rst
@@ -1,7 +1,7 @@
-About RIVET
+About
 =====================================
 
-RIVET is a tool for topological data analysis, and more specifically, for the visualization and analysis of two-parameter persistent homology.  RIVET was initially designed with interactive visualization foremost in mind, and this continues to be a central focus.  But RIVET also provides functionality for two-parameter persistence computation that should be useful regardless of whether the user wishes to do any visualization.  
+RIVET is a tool for topological data analysis, and more specifically, for the visualization and analysis of two-parameter persistent homology.  RIVET was initially designed with interactive visualization foremost in mind, and this continues to be a central focus.  But RIVET also provides functionality for two-parameter persistence computation that should be useful for other purposes as well.  
 
 Many of the mathematical and algorithmic ideas behind RIVET are explained in detail in the paper “|RIVET_Paper|.”  Additional papers  describing other aspects of RIVET are in preparation.
 
@@ -10,7 +10,7 @@ Many of the mathematical and algorithmic ideas behind RIVET are explained in det
    <a href="http://arxiv.org/abs/1512.00180"  target="_blank" rel="noopener">Interactive Visualization of 2-D Persistence Modules</a>
 
 
-RIVET is written in C++, and depends on the |qt_Link|, |Boost_Link|, and |MessagePack_Link| libraries.  In addition, RIVET now incorporates some code from |PHAT_Link|.  
+RIVET is written in C++, and depends on the |qt_Link|, |Boost_Link|, and |MessagePack_Link| libraries.  In addition, RIVET now incorporates some modified code from |PHAT_Link|.  
 
 
 .. |qt_Link| raw:: html 
@@ -29,23 +29,33 @@ RIVET is written in C++, and depends on the |qt_Link|, |Boost_Link|, and |Messag
 
    <a href="https://bitbucket.org/phat-code/phat/src/master/" target="_blank">PHAT</a>
 
+Overview
+--------
+
+The basic idea of 2-parameter persistent homology is simple: Given a data set (for example, a point cloud in \\(\\mathbb R^n\\), one constructs a 2-parameter family of simplicial complexes called a *bifiltration* whose topological structure captures some geometric structure of interest about the data.  For example, the bifiltration may encode information about the presence of clusters, holes, or tendrils in the data.  Applying simplicial homology to the bifiltration gives a diagram of vector spaces called a *2-parameter persistence module*, which algebraically encodes information about the topological structure of the bifiltration.  In contrast to the 1-parameter case, 2-parameter persistence modules can have very delicate algebraic structure.  As result, there is (in a sense that can be made precise) no good definition of a barcode for 2-parameter persistence modules.
+
+Nevertheless, one can define invariants of 2-parameter persistence modules that capture aspects of their structure relevant for data analysis.  RIVET computes and visualizes three such kinds of invariants, the *Hilbert function*, the *bigraded Betti numbers*, and the *fibered barcode.*  
+
+The fibered barcode is a parameterized family of barcodes obtained by restricting a 2-parameter persistence module to various lines in parameter space.  A key feature of RIVET is that it computes a data structure called the *augmented arrangement* on which fast queries of these barcodes can be performed.  These queries are used by RIVET's GUI to provide an interactive visualization of the fibered barcode.
+
+RIVET also computes *minimal presentations* of 2-parameter persistence modules.  These are specifications of the full algebraic structure of a persistence module which are as small as possible, in a certain sense.  Those who wish to study invariants of  2-parameter persistent homology not computed by RIVET may find it useful to take the minimal presentations output by RIVET as a starting point.  In practice, when working with real data, these presentations are often surprisingly small.
 
 Contributors
 ------------
 
-RIVET project was founded by |Lesnick_Link| and |Wright_Link|.  In 2013-2015 they designed and developed a first version of RIVET.  Matthew was the sole author of the code during this time. Since 2016, several others have made valuable contributions to RIVET, some of which will be incorporated into later releases.
+RIVET project was founded by |Lesnick_Link| and |Wright_Link|, who designed and developed a first version of RIVET in 2013-2015.  Matthew was the sole author of the code during this time. Since 2016, several others have made valuable contributions to RIVET, some of which will be incorporated into later releases.
 
 Here is a list of contributors, with a brief, incomplete summary of contributions:
 
-* Madkour Abdel-Rahman (St. Olaf College): Error handling 	
-* |Keller_Link| (Intel Labs): Parallel-friendly code organization, command line interactivity, API, Python wrappers, software design leadership.
-* |Lesnick_Link| (Princeton): Design, performance optimizations, computation of minimal presentations
-* Phil Nadolny (St. Olaf College): Error handling, code for constructing path through dual graph
-* |Wright_Link| (St. Olaf College): Design, primary developer
-* Simon Segert (Princeton) Major improvements to the GUI, extensions of RIVET 
-* David Turner (Princeton) Parallel minimization of a presentation
-* Alex Yu (Princeton) Extensions of RIVET 
-* |Zhao_Link| (Berkeley): Handling of multicritical bifiltrations and Degree-Rips bifiltrations, performance optimizations 
+* Madkour Abdel-Rahman : Error handling 	
+* |Keller_Link| : Parallel-friendly code organization, command line interactivity, API, Python wrappers, software design leadership.
+* |Lesnick_Link| : Design, performance optimizations, computation of minimal presentations
+* Phil Nadolny : Error handling, code for constructing path through dual graph
+* |Wright_Link| : Design, primary developer
+* Simon Segert : Major improvements to the GUI, extensions of RIVET 
+* David Turner : Parallel minimization of a presentation
+* Alex Yu : Extensions of RIVET 
+* |Zhao_Link| : Multicritical bifiltrations and Degree-Rips bifiltrations, performance optimizations 
 
 .. |Lesnick_Link| raw:: html 
 
@@ -63,6 +73,7 @@ Here is a list of contributors, with a brief, incomplete summary of contribution
 
    <a href="https://math.berkeley.edu/~rhzhao/" target="_blank">Roy Zhao</a>
 
+The RIVET development team can be reached by email at info@rivet.online.
 
 Contributing
 ------------
@@ -82,6 +93,7 @@ Issues
 A full list of bugs and todos can be found on the `Github issue tracker <https://github.com/rivetTDA/rivet/issues>`_.
 Please feel free to add any bugs/issues you discover, if not already listed.
 
+
 Acknowledgments
 ---------------
 

diff --git a/docs/console.rst b/docs/console.rst
@@ -0,0 +1,2 @@
+Using **rivet_console**
+=======================
diff --git a/docs/images/flowchart.pdf b/docs/images/flowchart.pdf
diff --git a/docs/flowchart.tex → docs/images/flowchart.tex b/docs/flowchart.tex → docs/images/flowchart.tex
@@ -1,7 +1,8 @@
-\documentclass{article}
+\documentclass[crop,tikz]{standalone}
 \pagestyle{empty}
 \usepackage[utf8]{inputenc}
 \usepackage{tikz}
+
 \usetikzlibrary{shapes.geometric, arrows}
 
 \tikzstyle{box} = [rectangle, rounded corners, minimum width=3cm, minimum height=1cm,text centered, draw=black, thick, fill=green!30]
@@ -10,36 +11,43 @@
 \tikzstyle{yellowBoxRedBorder} = [rectangle, rounded corners, minimum width=3cm, minimum height=1cm, text centered, draw=red, thick, fill=yellow!30]
 \tikzstyle{plainBox} = [rectangle, rounded corners, minimum width=3cm, minimum height=1cm, text centered, draw=black, thick]
 \tikzstyle{plainBoxRedBorder} = [rectangle, rounded corners, minimum width=3cm, minimum height=1cm, text centered, draw=red,thick]
-\tikzstyle{dataBox} = [rectangle, rounded corners, minimum width=8.0cm, minimum height=4.1cm,text centered, draw=black,thick, fill=gray!10]
-\tikzstyle{invariantBox} = [rectangle, rounded corners, minimum width=4.7cm, minimum height=8.1cm,text centered, draw=black,thick, fill=blue!10]
+
+\tikzstyle{dataBox} = [rectangle, rounded corners, minimum width=9.0cm, minimum height=4.9cm,text centered, draw=black,thick, fill=gray!10]
+\tikzstyle{invariantBox} = [rectangle, rounded corners, minimum width=5.5cm, minimum height=8cm,text centered, draw=black,thick, fill=blue!10]
+
 \tikzstyle{arrow} = [thick,->,>=stealth]
 
 \begin{document}
-
 \begin{tikzpicture}[node distance=1.9cm]
 
+\node (data) [dataBox,yshift=-2.1cm,xshift=-.3cm] {};
+\node (dataLabel)[xshift=.2cm] {\textbf{Data}};
+
 \node (pointsAnchor) [yshift = -1cm] {};
-\node (data) [dataBox,yshift=-1.7cm,xshift=-.3cm] {};
-\node (dataLabel) {\textbf{Data}};
 \node (metricAnchor) [below of= pointsAnchor] {};
-\node (pointsFun) [box,left of=pointsAnchor] {Point Cloud w/ Function};
-\node (points) [box,right of=pointsAnchor] {Point Cloud};
-\node (metricFun) [box,left of=metricAnchor] {Metric Space w/ Function};
-\node (metric) [box,right of=metricAnchor] {Metric Space};
-\node (bifiltration) [box, below of=metricAnchor,yshift=-.8cm] {Bifiltration};
+\node (pointsFun) [box,left of=pointsAnchor,xshift=-.5cm] {Point Cloud w/ Function};
+\node (points) [box,right of=pointsAnchor,xshift=.5cm] {Point Cloud};
+\node (metricFun) [box,left of=metricAnchor,xshift=-.5cm,yshift=-.8cm] {Metric Space w/ Function};
+\node (metric) [box,right of=metricAnchor,xshift=.5cm,yshift=-.8cm] {Metric Space};
+
+\node (bifiltration) [box, below of=metricAnchor,yshift=-1.6cm] {Bifiltration};
 %\node (input) [yellowBox,left of= bifiltration, xshift=-5cm] {Text File Input};
-\node (firep) [box, below of=bifiltration] {firep (short chain complex of free modules)};
-\node (magicAnchor) [below of= firep,yshift=-1.7cm] {};
-\node (minpres) [yellowBox, left of=magicAnchor,xshift=-.8cm] {Minimal Presentation};
-\node (invariant) [invariantBox,right of= magicAnchor,xshift=.8cm,yshift=-2.7cm] {};
-\node (invariantLabel) [right of= magicAnchor,xshift=2.0cm,yshift=.95cm] {\textbf{Invariants}};
-\node (hilbert)[yellowBoxRedBorder, right of= magicAnchor,xshift=.8cm]{Hilbert Function};
+
+\node (firep) [box, below of=bifiltration,yshift=-.8cm] {FIRep (short chain complex of free modules)};
+
+\node (magicAnchor) [below of= firep,yshift=-.8cm] {};
+\node (minpres) [yellowBox, left of=magicAnchor,xshift=-1.2cm] {Minimal Presentation};
+
+\node (invariant) [invariantBox,right of= magicAnchor,xshift=1.2cm,yshift=-3.1cm] {};
+\node (invariantLabel) [below of=invariant,yshift=-1.5cm] {\textbf{Invariants RIVET Visualizes}};
+\node (hilbert)[yellowBoxRedBorder, right of= magicAnchor,xshift=1.2cm]{Hilbert Function};
+
 \node (bettiCombine) [coordinate,below of= hilbert,yshift=.8cm] {};
 \node (betti) [yellowBoxRedBorder, below of= bettiCombine,yshift=.8cm]{Bigraded Betti Numbers};
-\node (arrangementCombine)[coordinate, below of= minpres,yshift=-1cm] {};
-\node (arrangement)[plainBoxRedBorder, below of= arrangementCombine,yshift=.3cm] {Augmented Arrangement};
-\node (barcodes)[yellowBox, below of= hilbert, yshift=-4cm]  {Barcodes of 1-D slices};
-\node (visualization)[plainBox, below of= barcodes,yshift=-1cm]  {Visualization};
+\node (arrangementCombine)[coordinate, below of= minpres,yshift=-1.3cm] {};
+\node (arrangement)[plainBoxRedBorder, below of= arrangementCombine,yshift=.8cm] {Augmented Arrangement};
+\node (barcodes)[yellowBox, below of= hilbert, yshift=-3.5cm]  {Barcodes of 1-D slices};
+%\node (visualization)[plainBox, below of= barcodes,yshift=-1cm]  {Visualization};
 %\node (minpres) [box, below of=firep, yshift=-0.5cm] {Minimal Presentation};
 %\node (pro2a) [process, below of=minpres, yshift=-0.5cm] {};
 %\node (pro2b) [process, right of=minpres, xshift=2cm] {Process 2b};
@@ -48,27 +56,27 @@
 %\draw [arrow] (input) -- (data);
 %\draw [arrow] (input) -- (bifiltration);
 %\draw [arrow] (input) -- (firep);
-\draw [arrow] (points) --  node[anchor=east,xshift=-0.3cm]{Euclidean distance} (metric);
+\draw [arrow] (points) --  node[anchor=east,xshift=-0.7cm]{Euclidean distance} (metric);
 \draw [arrow] (pointsFun) --  (metricFun);
-\draw [arrow] (metric) -- node[anchor=west]{degree-Rips}(bifiltration);
-\draw [arrow] (metricFun) -- node[anchor=east]{function-Rips} (bifiltration);
+\draw [arrow] (metric) -- node[anchor=west,yshift=-.1cm]{degree-Rips}(bifiltration);
+\draw [arrow] (metricFun) -- node[anchor=east,yshift=-.1cm]{function-Rips} (bifiltration);
 \draw [arrow] (bifiltration) -- node[anchor=west]{simplicial chains; trick of Chacholski et al.} (firep);
 \draw [arrow] (firep) -- node[anchor=west,xshift=.2cm,yshift=.05cm]{sparse lin. alg.} (minpres);
 \draw [arrow] (firep) -- (hilbert);
 \draw [thick] (minpres) -- (bettiCombine);
 \draw [thick] (hilbert) -- (bettiCombine);
 \draw [arrow] (bettiCombine) -- (betti);
-\draw [thick] (betti) -- node[anchor=west,xshift=-1.5cm,yshift=-.5cm]{line arrangement}(arrangementCombine);
+\draw [thick] (betti) -- node[anchor=west,xshift=-1.7cm,yshift=.4cm]{line arrangement}(arrangementCombine);
 \draw [thick] (minpres) -- node[anchor=east]{barcode templates}(arrangementCombine);
 \draw [arrow] (arrangementCombine) -- (arrangement);
-\draw [arrow] (invariant) -- (visualization);
+%\draw [arrow] (invariant) -- (visualization);
 %\draw [arrow] (minpres) -- node[anchor=east] {yes} (pro2a);
 %\draw [arrow] (minpres) -- node[anchor=south] {no} (pro2b);
 %\draw [arrow] (pro2b) |- (firep);
 %\draw [arrow] (pro2a) -- (out1);
 %\draw [arrow] (out1) -- (stop);
 
-\draw [arrow] (arrangement) -- node[anchor=east,yshift=-.3cm]{fast queries} (barcodes);
+\draw [arrow] (arrangement) -- node[anchor=east,xshift=.1cm,yshift=-.3cm]{fast queries} (barcodes);
 \end{tikzpicture}
 
 \end{document}
diff --git a/docs/index.rst b/docs/index.rst
@@ -12,15 +12,12 @@ RIVET Documentation
 
    about
    installing    
-   overview		
+   preliminaries
+   structure		
+   visualization
    running
-   understanding
    inputdata
-   output
-   FAQ
-
-
-
+   console   
 
 
 Indices and tables

diff --git a/docs/installing.rst b/docs/installing.rst
@@ -1,16 +1,9 @@
-Installing RIVET
+Installation
 ================
 
 RIVET is available at https://github.com/rivetTDA/rivet.
 
 
-Dependencies
-------------
-
-RIVET depends on the `Qt <https://www.qt.io/>`_, `Boost <http://www.boost.org/>`_, and `MessagePack <https://msgpack.org/index.html>`_ libraries.  
-In addition, RIVET now incorporates some code from `PHAT <https://bitbucket.org/phat-code/phat/src/master/>`_.
-
-
 Requirements
 ------------
 
@@ -21,7 +14,7 @@ Before starting to build RIVET, you will need to have the following installed:
 * Qt 5
 * Boost (version 1.58 or newer)
 
-Below we give step-by-step instructions for installing these required dependencies and building RIVET on Ubuntu and Mac OS X.  Building RIVET on Windows is not yet supported (we are working on this), but it is possible to build RIVET using the Bash shell on Windows 10.
+Below we give step-by-step instructions for installing these required dependencies and building RIVET on Ubuntu and Mac OS X.  Building RIVET on Windows is not yet supported, but it is possible to build RIVET using the Bash shell on Windows 10.
 
 
 .. _buildingOnUbuntu: