edu.stanford.math.plex

Class Plex

java.lang.Object

edu.stanford.math.plex.Plex

public class Plex
extends java.lang.Object

The Plex class provides some utility functions that don't have a clearly defined home, and some entry points into plex library code that are especially useful when in matlab. It is (apparently) impossible in matlab to execute code like new PlexClass(), so we provide static methods for creating Plex objects in matlab. The naming convention for these methods is that the constructor for instances of PlexClass will be named PlexClass(), and its argument spectrum will be whatever the usual form (or forms) of the associated constuctor are.

Version:

$Id$

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Plex.BettiNumbers An array of Betti numbers (int[]) boxed up for convenience.

Field Summary

Fields

Modifier and Type	Field and Description
protected static java.util.Random	rand
protected static boolean	useMessageWindow

Constructor Summary

Constructors

Constructor and Description
Plex()

Method Summary

Methods

Modifier and Type	Method and Description
protected static boolean	d_okay(double[][] d)
static DistanceData	DistanceData(double[][] d) Create a DistanceData instance.
static boolean	equalPersistenceIntervals(PersistenceInterval.Float[] arg1, PersistenceInterval.Float[] arg2, double delta) Are two PersistenceInterval.Float[] arguments sufficiently equal?
static EuclideanArrayData	EuclideanArrayData(double[][] data) Create a EuclideanArrayData instance from a double[][].
static EuclideanArrayData	EuclideanArrayData(double[] data, int dimension) Create a EuclideanArrayData instance from a data array.
static EuclideanArrayData	EuclideanArrayData(int num_pts, int dimension) Create a random EuclideanArrayData instance.
static EuclideanArrayData	EuclideanArrayData(java.lang.String filename) Create a EuclideanArrayData instance from a text file containing a distance matrix.
static ExplicitStream	ExplicitStream() Make an empty ExplicitStream.
protected static PersistenceInterval.Float[]	filter_pintervals(PersistenceInterval.Float[] vec, double delta)
static Plex.BettiNumbers	FilterInfinite(PersistenceBasisInterval[] coll) Summarize the semi-infinite PersistenceBasisIntervals.
static Plex.BettiNumbers	FilterInfinite(PersistenceInterval[] coll) Summarize the semi-infinite PersistenceIntervals.
protected static int	firstSmallerPtIndex(int arg, int lo, int[] pts)
static int	intersection_count(int[] v1, int[] v2)
protected static boolean	is_permutation(int[] perm)
static LazyWitnessStream	LazyWitnessStream(double delta, int max_d, double R, int nu, int[] landmarks, PointData data) Make a stream of the simplices in a lazy Witness complex for data.
static void	main(java.lang.String[] args) Entry point to Plex from the java interpreter.
static ExplicitStream	makeExplicit(SimplexStream str) Convert a SimplexStream into an explicit one.
static PlexMessageWindow	messageWindow(java.lang.String title) Make a Plex message window.
protected static double	normalizeUpperBound(double arg)
static Persistence	Persistence() Create a Persistence instance.
static PersistenceBasis	PersistenceBasis() Create a PersistenceBasis instance.
static void	plot(PersistenceBasisInterval[] arg, java.lang.String label, double upperBound) Plot an array of Plex barcodes computed with bases.
static void	plot(PersistenceInterval[] arg, java.lang.String label, double upperBound) Plot an array of Plex barcodes (that is, a PersistenceInterval[]).
protected static double[][][]	printable_intervals(PersistenceInterval[] arg)
protected static boolean	ptArrayIsSubset(int[] ipts, int[] jpts)
static void	random_index_subset(int N, int[] subset, int subset_size) Take subset_size distinct entries from the integers 0 through N-1, and put them in the initial segment of subset[].
static void	random_permutation(int[] perm) Make a random permutation of the integers 0 through perm.length-1 and put them in perm.
static void	random_subset(int[] set, int[] subset) Take subset.length distinct entries from set[], and put them in subset[].
static void	random_subset(int[] set, int set_size, int[] subset, int subset_size) Take subset_size distinct entries from initial segment of length set_size in set[] and put them in the initial segment of subset[].
static void	random_subset(int N, int[] subset) Take subset.length distinct entries from the integers 1 through N, and put them in subset[].
static void	random_subset(int N, int[] subset, int subset_size) Take subset_size distinct entries from the integers 1 through N, and put them in the initial segment of subset[].
static double[][]	readMatrix(java.io.Reader input) Read a double[][] from a stream.
static double[][]	readMatrix(java.lang.String inputFilename) Read a double[][] from a file.
static RipsStream	RipsStream(double delta, int max_d, double max_distance, PointData data) Make a stream of the simplices in a Rips complex for given data set.
static void	scatter(PersistenceBasisInterval[] arg, java.lang.String label, double upperBound) Make a scatterplot of a PersistenceBasisInterval[].
static void	scatter(PersistenceInterval[] arg, java.lang.String label, double upperBound) Make a scatterplot of a PersistenceInterval[].
static SimplexStream.Stack	SimplexStack(int max_findex, int max_dimension) Create an empty SimplexStream.Stack.
static SimplexTable	SimplexTable(int limit) Make a new SimplexTable.
static int	sorted_intersection_count(int[] v1, int[] v2) Compute the overlap size for two sorted arrays using the zipper algorithm.
static Torus	Torus(int n, int d) Create a Torus with a given granulatity.
static java.lang.String	toString(byte[] x) Take an array of byte and make a string.
static java.lang.String	toString(byte[] x, int max_entries) Take an array of byte and make a string.
static java.lang.String	toString(double[] x) Take an array of double and make a string.
static java.lang.String	toString(double[][] x) Take an double[][] and make a string.
static java.lang.String	toString(double[][] x, int max_entries) Take an array of double[] and make a string.
static java.lang.String	toString(double[] x, int max_entries) Take an array of double and make a string.
static java.lang.String	toString(int[] x) Take an array of int and make a string.
static java.lang.String	toString(int[][] x) Take an int[][] and make a string.
static java.lang.String	toString(int[][] x, int max_entries) Take an array of int[] and make a string.
static java.lang.String	toString(int[] x, int max_entries) Take an array of int and make a string.
static java.lang.String	toString(long[] x) Take an array of long and make a string.
static java.lang.String	toString(long[] x, int max_entries) Take an array of long and make a string.
static boolean	useMessageWindow() Should we use a PlexMessageWindow for messages?
static void	useMessageWindow(boolean flag) Use a PlexMessageWindow for messages?
static WitnessStream	WitnessStream(double delta, int max_d, double R, int[] landmarks, PointData data) Make a stream of the simplices in a Witness complex for data.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

rand

protected static java.util.Random rand

useMessageWindow

protected static boolean useMessageWindow

Constructor Detail

Plex

public Plex()

Method Detail

intersection_count

public static int intersection_count(int[] v1,
                     int[] v2)

sorted_intersection_count

public static int sorted_intersection_count(int[] v1,
                            int[] v2)

Compute the overlap size for two sorted arrays using the zipper algorithm.

Parameters:

v1 - First sorted array.

v2 - Second sorted array.

Returns:

The number of common elements of v1 and v2.

random_subset

public static void random_subset(int[] set,
                 int set_size,
                 int[] subset,
                 int subset_size)

Take subset_size distinct entries from initial segment of length set_size in set[] and put them in the initial segment of subset[]. The ordering of the entries is preserved -- that is, if set[i] and set[i+d] both go into subset, the index of set[i] is less than that of set[i+d].

Parameters:

set - an int[] from which to select.

set_size - an int specifying how many entries to use.

subset - an int[] in which to deposit the selections.

subset_size - an int specifying how many entries to select.

random_subset

public static void random_subset(int[] set,
                 int[] subset)

Take subset.length distinct entries from set[], and put them in subset[].

Parameters:

set - an int[] from which to select.

subset - an int[] in which to deposit the selections.

random_subset

public static void random_subset(int N,
                 int[] subset,
                 int subset_size)

Take subset_size distinct entries from the integers 1 through N, and put them in the initial segment of subset[].

Parameters:

N - an int specifying the range from which to choose the subset.

subset - an int[] in which to deposit the selections.

subset_size - an int specifying how many entries to use.

random_subset

public static void random_subset(int N,
                 int[] subset)

Take subset.length distinct entries from the integers 1 through N, and put them in subset[].

Parameters:

N - an int specifying the range from which to choose the subset.

subset - an int[] in which to deposit the selections.

is_permutation

protected static boolean is_permutation(int[] perm)

random_permutation

public static void random_permutation(int[] perm)

Make a random permutation of the integers 0 through perm.length-1 and put them in perm.

Parameters:

perm - an int[] to hold a random permutation.

toString

public static java.lang.String toString(int[] x,
                        int max_entries)

Take an array of int and make a string.

Parameters:

x - an int[] we want to examine.

max_entries - The maximum number of entries we wish to examine.

Returns:

A String instance that "looks like" x.

toString

public static java.lang.String toString(int[] x)

Take an array of int and make a string.

Parameters:

x - an int[] we want to examine.

Returns:

A String instance that "looks like" x.

toString

public static java.lang.String toString(byte[] x,
                        int max_entries)

Take an array of byte and make a string.

Parameters:

x - an byte[] we want to examine.

max_entries - The maximum number of entries we wish to examine.

Returns:

A String instance that "looks like" x.

toString

public static java.lang.String toString(byte[] x)

Take an array of byte and make a string.

Parameters:

x - an byte[] we want to examine.

Returns:

A String instance that "looks like" x.

toString

public static java.lang.String toString(int[][] x,
                        int max_entries)

Take an array of int[] and make a string.

Parameters:

x - an int[][] we want to examine.

max_entries - The maximum number of entries we wish to examine.

Returns:

A String instance that "looks like" x.

toString

public static java.lang.String toString(int[][] x)

Take an int[][] and make a string.

Parameters:

x - an int[][] we want to examine.

Returns:

A String instance that "looks like" x.

toString

public static java.lang.String toString(double[] x,
                        int max_entries)

Take an array of double and make a string.

Parameters:

x - a double[] we want to examine.

max_entries - The maximum number of entries we wish to examine.

Returns:

A String instance that "looks like" x.

toString

public static java.lang.String toString(double[] x)

Take an array of double and make a string.

Parameters:

x - a double[] we want to examine.

Returns:

A String instance that "looks like" x.

toString

public static java.lang.String toString(double[][] x,
                        int max_entries)

Take an array of double[] and make a string.

Parameters:

x - an double[][] we want to examine.

max_entries - The maximum number of entries we wish to examine.

Returns:

A String instance that "looks like" x.

toString

public static java.lang.String toString(double[][] x)

Take an double[][] and make a string.

Parameters:

x - an double[][] we want to examine.

Returns:

A String instance that "looks like" x.

toString

public static java.lang.String toString(long[] x,
                        int max_entries)

Take an array of long and make a string.

Parameters:

x - a long[] we want to examine.

max_entries - The maximum number of entries we wish to examine.

Returns:

A String instance that "looks like" x.

toString

public static java.lang.String toString(long[] x)

Take an array of long and make a string.

Parameters:

x - a long[] we want to examine.

Returns:

A String instance that "looks like" x.

random_index_subset

public static void random_index_subset(int N,
                       int[] subset,
                       int subset_size)

Take subset_size distinct entries from the integers 0 through N-1, and put them in the initial segment of subset[].

Parameters:

N - an int specifying the range from which to choose the subset.

subset - an int[] in which to deposit the selections.

subset_size - an int specifying how many entries to use.

firstSmallerPtIndex

protected static int firstSmallerPtIndex(int arg,
                      int lo,
                      int[] pts)

ptArrayIsSubset

protected static boolean ptArrayIsSubset(int[] ipts,
                      int[] jpts)

FilterInfinite

public static Plex.BettiNumbers FilterInfinite(PersistenceInterval[] coll)

Summarize the semi-infinite PersistenceIntervals.

Parameters:

coll - A collection of PersistenceIntervals.

Returns:

An instance of Plex.BettiNumbers.

FilterInfinite

public static Plex.BettiNumbers FilterInfinite(PersistenceBasisInterval[] coll)

Summarize the semi-infinite PersistenceBasisIntervals.

Parameters:

coll - A collection of PersistenceBasisIntervals.

Returns:

An isntance of Plex.BettiNumbers.

SimplexStack

public static SimplexStream.Stack SimplexStack(int max_findex,
                               int max_dimension)

Create an empty SimplexStream.Stack.

The object returned from this method can be used to create a new SimplexStream from the contents of another one, or using an Interator constructed from such a stream.

Parameters:

max_findex - Largest filtration index used by entries in this stream.

max_dimension - Maximum dimension of Simplex instances stored in this stream.

Returns:

An empty SimplexStream.Stack.

Persistence

public static Persistence Persistence()

Create a Persistence instance.

Used to calculate persistent homology; e.g., p.computeIntervals(stream).

Returns:

A new Persistence instance.

PersistenceBasis

public static PersistenceBasis PersistenceBasis()

Create a PersistenceBasis instance.

Used to calculate persistent homology returning bases for the resulting intervals; e.g., p.computeIntervals(stream).

Returns:

A new PersistenceBasis instance.

EuclideanArrayData

public static EuclideanArrayData EuclideanArrayData(int num_pts,
                                    int dimension)

Create a random EuclideanArrayData instance.

Parameters:

num_pts - How many points.

dimension - Dimension of the space.

Returns:

A randomly generated EuclideanArrayData instance.

EuclideanArrayData

public static EuclideanArrayData EuclideanArrayData(double[] data,
                                    int dimension)

Create a EuclideanArrayData instance from a data array.

Parameters:

data - The data.

dimension - The dimension of the data.

Returns:

EuclideanArrayData instance encapsulating the argument data.

EuclideanArrayData

public static EuclideanArrayData EuclideanArrayData(double[][] data)

Create a EuclideanArrayData instance from a double[][].

Parameters:

data - The data.

Returns:

EuclideanArrayData instance encapsulating the argument data.

EuclideanArrayData

public static EuclideanArrayData EuclideanArrayData(java.lang.String filename)

Create a EuclideanArrayData instance from a text file containing a distance matrix.

Parameters:

filename - The name of the datafile.

Returns:

EuclideanArrayData instance encapsulating the argument data.

readMatrix

public static double[][] readMatrix(java.io.Reader input)

Read a double[][] from a stream. The format is fairly general, where the elements are separated by whitespace and all the elements for each row appear on a single line, and the last row is followed by a blank line.

Parameters:

input - A Reader instance.

Returns:

The matrix as a double[][].

readMatrix

public static double[][] readMatrix(java.lang.String inputFilename)

Read a double[][] from a file. The format is fairly general, where the elements are separated by whitespace and all the elements for each row appear on a single line, and the last row is followed by a blank line.

Parameters:

inputFilename - An input file.

Returns:

The matrix as a double[][].

d_okay

protected static boolean d_okay(double[][] d)

DistanceData

public static DistanceData DistanceData(double[][] d)

Create a DistanceData instance.

Parameters:

d - The distance matrix

Returns:

A DistanceData instance.

Torus

public static Torus Torus(int n,
          int d)

Create a Torus with a given granulatity.

Parameters:

n - Split the Torus into n^^d squares, return the corners.

Returns:

PointData for a d-dimensional Torus.

RipsStream

public static RipsStream RipsStream(double delta,
                    int max_d,
                    double max_distance,
                    PointData data)

Make a stream of the simplices in a Rips complex for given data set.

Parameters:

delta - Granularity to apply to the underlying metric.

max_distance - Maximum edge length we will consider.

max_d - Maximum dimension of Simplex instances we construct.

data - Metric data to use in constructing stream.

Returns:

A SimplexStream.Stack containing the Rips complex.

ExplicitStream

public static ExplicitStream ExplicitStream()

Make an empty ExplicitStream. These are normally populated "by hand".

Returns:

An empty ExplicitStream.

makeExplicit

public static ExplicitStream makeExplicit(SimplexStream str)

Convert a SimplexStream into an explicit one.

Parameters:

str - A SimplexStream instance.

Returns:

An ExplicitStream with equivalent Simplex entries.

SimplexTable

public static SimplexTable SimplexTable(int limit)

Make a new SimplexTable.

Parameters:

limit - An upper bound on the number of simplices that will be interned in the table.

Returns:

An empty SimplexTable.

See Also:

SimplexTable.SimplexTable(int)

WitnessStream

public static WitnessStream WitnessStream(double delta,
                          int max_d,
                          double R,
                          int[] landmarks,
                          PointData data)

Make a stream of the simplices in a Witness complex for data.

Parameters:

delta - Granularity to apply to the underlying metric.

max_d - Maximum dimension of Simplex instances we construct.

R - Maximum R we will use.

landmarks - Indices of points to use as landmarks. The simplices constructed will use the landmark indices, rather than the indices into data.

data - Metric data to use in constructing stream.

Returns:

A WitnessStream for the given data.

LazyWitnessStream

public static LazyWitnessStream LazyWitnessStream(double delta,
                                  int max_d,
                                  double R,
                                  int nu,
                                  int[] landmarks,
                                  PointData data)

Make a stream of the simplices in a lazy Witness complex for data.

Parameters:

delta - Granularity to apply to the underlying metric.

max_d - Maximum dimension of Simplex instances we construct.

R - Maximum R we will use.

nu - See Topological estimation using witness complexes, above.

landmarks - Indices of points to use as landmarks. The simplices constructed will use the landmark indices, rather than the indices into data.

data - Metric data to use in constructing stream.

Returns:

A LazyWitnessStream for the given data.

filter_pintervals

protected static PersistenceInterval.Float[] filter_pintervals(PersistenceInterval.Float[] vec,
                                            double delta)

equalPersistenceIntervals

public static boolean equalPersistenceIntervals(PersistenceInterval.Float[] arg1,
                                PersistenceInterval.Float[] arg2,
                                double delta)

Are two PersistenceInterval.Float[] arguments sufficiently equal?

Parameters:

arg1 - PersistenceInterval.Float[].

arg2 - PersistenceInterval.Float[].

delta - double

Returns:

true if the arguments are equivalent up the precision of the stream and delta.

normalizeUpperBound

protected static double normalizeUpperBound(double arg)

printable_intervals

protected static double[][][] printable_intervals(PersistenceInterval[] arg)

plot

public static void plot(PersistenceInterval[] arg,
        java.lang.String label,
        double upperBound)

Plot an array of Plex barcodes (that is, a PersistenceInterval[]).

Parameters:

arg - PersistenceInterval[].

label - A String to use as the label.

upperBound - A limit on the plot width. This limit is not strict. The actual plotted range will be at least this size, and no larger than 10% greater.

plot

public static void plot(PersistenceBasisInterval[] arg,
        java.lang.String label,
        double upperBound)

Plot an array of Plex barcodes computed with bases.

Parameters:

arg - PersistenceBasisInterval[].

label - A string to use as a label.

upperBound - A limit on the plot width. This limit is not strict. The actual plotted range will be at least this size, and no larger than 10% greater.

scatter

public static void scatter(PersistenceInterval[] arg,
           java.lang.String label,
           double upperBound)

Make a scatterplot of a PersistenceInterval[].

Parameters:

arg - PersistenceInterval[].

label - A String to use as the label.

upperBound - A limit on the plot width. This limit is not strict. The actual plotted range will be at least this size, and no larger than 10% greater.

scatter

public static void scatter(PersistenceBasisInterval[] arg,
           java.lang.String label,
           double upperBound)

Make a scatterplot of a PersistenceBasisInterval[].

Parameters:

arg - PersistenceBasisInterval[].

label - A String to use as the label.

upperBound - A limit on the plot width. This limit is not strict. The actual plotted range will be at least this size, and no larger than 10% greater.

useMessageWindow

public static void useMessageWindow(boolean flag)

Use a PlexMessageWindow for messages?

Parameters:

flag - Set useMessageWindow.

useMessageWindow

public static boolean useMessageWindow()

Should we use a PlexMessageWindow for messages?

Returns:

true if a PlexMessageWindow is preferable, else false.

messageWindow

public static PlexMessageWindow messageWindow(java.lang.String title)

Make a Plex message window.

Parameters:

title - Window title.

Returns:

A PlexMessageWindow instance.

main

public static void main(java.lang.String[] args)

Entry point to Plex from the java interpreter.

This stub will, when time permits, be turned into something that allows users to make some non-trivial use of Plex from the java launcher.

Parameters:

args - Strings that will need to be parsed.