Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added documentation with Sphinx and reStructuredText #126

Merged
merged 63 commits into from Aug 11, 2018
Merged
Changes from 1 commit
Commits
Show all changes
63 commits
Select commit Hold shift + click to select a range
6c5d00d
set up sphinx documentation and added some content
mlwright84 Jul 4, 2018
d89c53f
changed theme to sphinx_rtd_theme
mlwright84 Jul 6, 2018
ac432de
added documentation page about the RIVET visualization
mlwright84 Jul 6, 2018
cb4dcac
testing MathJax
mlwright84 Jul 6, 2018
cb12336
edited math syntax on understanding page
mlwright84 Jul 7, 2018
232d736
minor fixes
mlwright84 Jul 7, 2018
a8080f2
work on documentation
mlwright84 Jul 7, 2018
842831f
fixes to documentation
mlwright84 Jul 10, 2018
0b8d80c
Some progress on documentation; added two new files. Still needs a l…
mlesnick Jul 15, 2018
914fd8e
added JavaScript to open all external links in documentation in new w…
mlwright84 Jul 20, 2018
c6af8bf
Edits to documentation.
mlesnick Jul 21, 2018
feb6837
Good progress on the documentation. It's starting to come together.
mlesnick Jul 23, 2018
be7d3ae
Progress on documentation; in particular, fleshed out a better organi…
mlesnick Jul 24, 2018
86db0b0
More progress to the documentation. The section "Running RIVET" is i…
mlesnick Jul 26, 2018
0036b89
Gutted readme.me, added link to rivet.online.
mlesnick Jul 26, 2018
cc0aeae
more progress on Running RIVET. structure is starting to congeal. S…
mlesnick Jul 27, 2018
55bfcc4
More work on the documentation. Starting to converge.
mlesnick Jul 27, 2018
f240d5e
forgot to stage a file.
mlesnick Jul 27, 2018
7cde840
Merge branch 'ML_Doc_Edits' into sphinxdoc
mlesnick Jul 27, 2018
f62c20a
Added pic. Fixed typo.
mlesnick Jul 27, 2018
ddd2ddc
Update about.rst
mlesnick Jul 27, 2018
4407a39
Update about.rst
mlesnick Jul 27, 2018
cfb9ab4
Update about.rst
mlesnick Jul 27, 2018
9edc064
Update about.rst
mlesnick Jul 27, 2018
6f6498f
Update about.rst
mlesnick Jul 27, 2018
2ebb25d
Update about.rst
mlesnick Jul 27, 2018
9987fef
Update about.rst
mlesnick Jul 27, 2018
be71468
Small tweak.
mlesnick Jul 27, 2018
935d00d
Update about.rst
mlesnick Jul 27, 2018
3773046
Update about.rst
mlesnick Jul 28, 2018
5ca19ab
added example to documentation
mlwright84 Jul 31, 2018
d4418d8
small updates
mlwright84 Jul 31, 2018
df0f71d
updates and fixes
mlwright84 Jul 31, 2018
78874c8
small fixes; flowchart experiment
mlwright84 Jul 31, 2018
96631b2
testing flowchart in SVG format
mlwright84 Jul 31, 2018
d3096d3
simpler code for flowchart include
mlwright84 Jul 31, 2018
7e45c34
added instructions for building flowchart in SVG format
mlwright84 Jul 31, 2018
a719cda
typo fix
mlwright84 Jul 31, 2018
20ae28f
Added a couple of todos.
mlesnick Aug 5, 2018
0815df4
More typo fixes.
mlesnick Aug 5, 2018
0cca758
Added a todo in examples.rst
mlesnick Aug 5, 2018
3769b6b
Some tweaks to documentation.
mlesnick Aug 9, 2018
8b2da3c
Specify Betti/Hilbert output format.
mlesnick Aug 9, 2018
ab5e2b0
Tweaks.
mlesnick Aug 9, 2018
8749634
tweaks
mlesnick Aug 9, 2018
5c2ff36
another tweak.
mlesnick Aug 9, 2018
f070282
updates to the todos
mlwright84 Aug 9, 2018
7508522
Merge branch 'sphinxdoc' of https://github.com/mlwright84/rivet into …
mlwright84 Aug 9, 2018
b72f6e5
updated name of GUI to rivet_GUI
mlwright84 Aug 9, 2018
3db6a98
updated language in the help screen and file input box to match that …
mlwright84 Aug 9, 2018
9763fc8
small edits
mlwright84 Aug 10, 2018
a337a17
introduced 'bipersistece module' language
mlwright84 Aug 10, 2018
2aee335
added bibTex entry
mlwright84 Aug 10, 2018
582eb36
typo fix
mlwright84 Aug 10, 2018
57c6ebb
another typo fix
mlwright84 Aug 10, 2018
d865873
Some polish to example.rst
mlesnick Aug 10, 2018
bca34e2
Merge branch 'sphinxdoc' of https://github.com/mlwright84/rivet into …
mlesnick Aug 10, 2018
da39364
Touchup.
mlesnick Aug 10, 2018
9a0e501
added point cloud data file for the example in the documentation
mlwright84 Aug 10, 2018
8b795cd
added hyperlink to data file that will work after the pull request is…
mlwright84 Aug 10, 2018
bc9f52d
updated text in viewer to 'module invariants file'
mlwright84 Aug 10, 2018
a1744de
Some small and inconsequential tweaks. Removed an unused, file and r…
mlesnick Aug 10, 2018
3a863d4
Merge branch 'sphinxdoc' of https://github.com/mlwright84/rivet into …
mlesnick Aug 10, 2018
File filter...
Filter file types
Jump to…
Jump to file or symbol
Failed to load files and symbols.

Always

Just for now

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.
  • Loading branch information
mlesnick committed Jul 24, 2018
commit be7d3ae8b90f1de2f54a18157c38f01ebd6a6baf
@@ -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?
------------------------------------------

@@ -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
---------------

@@ -0,0 +1,2 @@
Using **rivet_console**
=======================
Binary file not shown.
@@ -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}
@@ -12,15 +12,12 @@ RIVET Documentation

about
installing
overview
preliminaries
structure
visualization
running
understanding
inputdata
output
FAQ



console


Indices and tables
@@ -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:
ProTip! Use n and p to navigate between commits in a pull request.
You can’t perform that action at this time.