SimplexTree: R6 Class for Simplex Tree
In rgudhi: An Interface to the GUDHI Library for Topological Data Analysis
SimplexTree R Documentation
R6 Class for Simplex Tree
Description
The simplex tree is an efficient and flexible data structure for
representing general (filtered) simplicial complexes. The data structure is
described in \insertCiteboissonnat2014simplex;textualrgudhi.
Details
This class is a filtered, with keys, and non contiguous vertices
version of the simplex tree.
References
\insertCited
Super class
rgudhi::PythonClass -> SimplexTree
Methods
Public methods
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Inherited methods
Method new()
The SimplexTree class constructor.
Usage
SimplexTree$new(py_class = NULL)
Arguments
py_classA Python SimplexTree class object. Defaults to NULL
which uses the Python class constructor instead.
Returns
A new SimplexTree object.
Method set_is_flag()
This function sets the internal field m_IsFlag which
records whether the simplex tree is a flag complex (i.e. has been
generated by a Rips complex).
Usage
SimplexTree$set_is_flag(val)
Arguments
valA boolean specifying whether the simplex tree is a flag
complex.
Details
The SimplexTree class initializes the m_IsFlag
field to FALSE by default and this method specifically allows to
overwrite this default value.
Returns
The updated SimplexTree class itself invisibly.
Method assign_filtration()
This function assigns a new filtration value to a given
N-simplex.
Usage
SimplexTree$assign_filtration(simplex, filtration)
Arguments
simplexAn integer vector representing the N-simplex in the form
of a list of vertices.
filtrationA numeric value specifying the new filtration value.
Details
Beware that after this operation, the structure may not be a
valid filtration anymore, a simplex could have a lower filtration value
than one of its faces. Callers are responsible for fixing this (with
more calls to the $assign_filtration() method or a call to the
$make_filtration_non_decreasing() method for instance) before calling
any function that relies on the filtration property, such as
persistence().
Returns
The updated SimplexTree class itself invisibly.
Method betti_numbers()
This function returns the Betti numbers of the simplicial
complex.
Usage
SimplexTree$betti_numbers()
Returns
An integer vector storing the Betti numbers.
Method collapse_edges()
Assuming the simplex tree is a 1-skeleton graph, this method
collapse edges (simplices of higher dimension are ignored) and resets
the simplex tree from the remaining edges. A good candidate is to build
a simplex tree on top of a RipsComplex of dimension 1 before
collapsing edges as done in this Python example.
For implementation details, please refer to
\insertCiteboissonnat2020edge;textualrgudhi.
Usage
SimplexTree$collapse_edges(nb_iterations = 1)
Arguments
nb_iterationsAn integer value specifying the number of edge
collapse iterations to perform. Defaults to 1L.
Details
It requires Eigen >= 3.1.0 and an exception is thrown if not
available.
References
\insertCited
Returns
The updated SimplexTree class itself invisibly.
Method compute_persistence()
This function computes the persistence of the simplicial
complex, so it can be accessed through $persistent_betti_numbers(),
$persistence_pairs(), etc. This function is equivalent to
$persistence() when you do not want the list that $persistence()
returns.
Usage
SimplexTree$compute_persistence(
homology_coeff_field = 11,
min_persistence = 0,
persistence_dim_max = FALSE
)
Arguments
homology_coeff_fieldAn integer value specifying the homology
coefficient field. Must be a prime number. Defaults to 11L. Maximum
is 46337L.
min_persistenceA numeric value specifying the minimum persistence
value to take into account (strictly greater than min_persistence).
Defaults to 0.0. Set min_persistence = -1.0 to see all values.
persistence_dim_maxA boolean specifying whether the persistent
homology for the maximal dimension in the complex is computed
(persistence_dim_max = TRUE). If FALSE, it is ignored. Defaults to
FALSE.
Returns
The updated SimplexTree class itself invisibly.
Method dimension()
This function returns the dimension of the simplicial
complex.
Usage
SimplexTree$dimension()
Details
This function is not constant time because it can recompute
dimension if required (can be triggered by $remove_maximal_simplex()
or $prune_above_filtration() methods for instance).
Returns
An integer value storing the simplicial complex dimension.
Method expansion()
Expands the simplex tree containing only its one skeleton
until dimension max_dim.
Usage
SimplexTree$expansion(max_dim)
Arguments
max_dimAn integer value specifying the maximal dimension to
expented the simplex tree to.
Details
The expanded simplicial complex until dimension d attached to
a graph G is the maximal simplicial complex of dimension at most d
admitting the graph G as 1-skeleton. The filtration value assigned to
a simplex is the maximal filtration value of one of its edges.
The simplex tree must contain no simplex of dimension bigger than 1 when
calling the method.
Returns
The updated SimplexTree class itself invisibly.
Method extend_filtration()
Extend filtration for computing extended persistence. This
function only uses the filtration values at the 0-dimensional
simplices, and computes the extended persistence diagram induced by the
lower-star filtration computed with these values.
Usage
SimplexTree$extend_filtration()
Details
Note that after calling this function, the filtration values are
actually modified within the simplex tree. The method
$extended_persistence() retrieves the original values.
Note that this code creates an extra vertex internally, so you should
make sure that the simplex tree does not contain a vertex with the
largest possible value (i.e., 4294967295).
This
notebook
explains how to compute an extension of persistence called extended
persistence.
Returns
The updated SimplexTree class itself invisibly.
Method extended_persistence()
This function retrieves good values for extended
persistence, and separate the diagrams into the Ordinary, Relative,
Extended+ and Extended- subdiagrams.
Usage
SimplexTree$extended_persistence(
homology_coeff_field = 11,
min_persistence = 0
)
Arguments
homology_coeff_fieldAn integer value specifying the homology
coefficient field. Must be a prime number. Defaults to 11L. Maximum
is 46337L.
min_persistenceA numeric value specifying the minimum persistence
value to take into account (strictly greater than min_persistence).
Defaults to 0.0. Set min_persistence = -1.0 to see all values.
Details
The coordinates of the persistence diagram points might be a
little different than the original filtration values due to the
internal transformation (scaling to [-2,-1]) that is performed on these
values during the computation of extended persistence.
This notebook explains how to compute an extension of persistence called
extended persistence.
Returns
A list of four persistence diagrams in the format described in
$persistence(). The first one is Ordinary, the second one is
Relative, the third one is Extended+ and the fourth one is
Extended-. See this
article
and/or Section 2.2 in this
article
for a description of these subtypes.
Method filtration()
This function returns the filtration value for a given
N-simplex in this simplicial complex, or +infinity if it is not in the
complex.
Usage
SimplexTree$filtration(simplex)
Arguments
simplexAn integer vector representing the N-simplex in the form
of a list of vertices.
Returns
A numeric value storing the filtration value for the input
N-simplex.
Method find()
This function returns if the N-simplex was found in the
simplicial complex or not.
Usage
SimplexTree$find(simplex)
Arguments
simplexAn integer vector representing the N-simplex in the form
of a list of vertices.
Returns
A boolean storing whether the input N-simplex was found in the
simplicial complex.
Method flag_persistence_generators()
Assuming this is a flag complex, this function returns the
persistence pairs, where each simplex is replaced with the vertices of
the edges that gave it its filtration value.
Usage
SimplexTree$flag_persistence_generators()
Returns
A list with the following components:
An n x 3 integer matrix containing the regular persistence pairs of
dimension 0, with one vertex for birth and two for death;
A list of m x 4 integer matrices containing the other regular
persistence pairs, grouped by dimension, with 2 vertices per extremity;
An l x ? integer matrix containing the connected components, with one
vertex each;
A list of k x 2 integer matrices containing the other essential
features, grouped by dimension, with 2 vertices for birth.
Method get_boundaries()
For a given N-simplex, this function returns a list of
simplices of dimension N-1 corresponding to the boundaries of the
N-simplex.
Usage
SimplexTree$get_boundaries(simplex)
Arguments
simplexAn integer vector representing the N-simplex in the form
of a list of vertices.
Returns
A tibble listing the (simplicies of the)
boundary of the input N-simplex in column simplex along with their
corresponding filtration value in column filtration.
Method get_cofaces()
This function returns the cofaces of a given N-simplex with
a given codimension.
Usage
SimplexTree$get_cofaces(simplex, codimension)
Arguments
simplexAn integer vector representing the N-simplex in the form
of a list of vertices.
codimensionAn integer value specifying the codimension. If
codimension = 0, all cofaces are returned (equivalent of
$get_star() function).
Returns
A tibble listing the (simplicies of the)
cofaces of the input N-simplex in column simplex along with their
corresponding filtration value in column filtration.
Method get_filtration()
This function retrieves the list of simplices and their
given filtration values sorted by increasing filtration values.
Usage
SimplexTree$get_filtration()
Returns
A tibble listing the simplicies in column
simplex along with their corresponding filtration value in column
filtration, in increasing order of filtration value.
Method get_simplices()
This function retrieves the list of simplices and their
given filtration values.
Usage
SimplexTree$get_simplices()
Returns
A tibble listing the simplicies in column
simplex along with their corresponding filtration value in column
filtration, in increasing order of filtration value.
Method get_skeleton()
This function returns a generator with the (simplices of
the) skeleton of a maximum given dimension.
Usage
SimplexTree$get_skeleton(dimension)
Arguments
dimensionA integer value specifying the skeleton dimension value.
Returns
A tibble listing the (simplicies of the)
skeleton of a maximum dimension in column simplex along with their
corresponding filtration value in column filtration.
Method get_star()
This function returns the star of a given N-simplex.
Usage
SimplexTree$get_star(simplex)
Arguments
simplexAn integer vector representing the N-simplex in the form
of a list of vertices.
Returns
A tibble listing the (simplicies of the)
star of a simplex in column simplex along with their corresponding
filtration value in column filtration.
Method insert()
This function inserts the given N-simplex and its subfaces
with the given filtration value. If some of those simplices are already
present with a higher filtration value, their filtration value is
lowered.
Usage
SimplexTree$insert(simplex, filtration = 0, chainable = TRUE)
Arguments
simplexAn integer vector representing the N-simplex in the form
of a list of vertices.
filtrationA numeric value specifying the filtration value of the
simplex. Defaults to 0.0.
chainableA boolean specifying whether the method should return the
class itself, hence allowing its use in pipe chaining. Defaults to TRUE,
which enables chaining.
Returns
The updated SimplexTree class itself invisibly if
chainable is set to TRUE (default behavior), or a boolean set to
TRUE if the simplex was not yet in the complex or FALSE otherwise
(whatever its original filtration value).
Method lower_star_persistence_generators()
Assuming this is a lower-star filtration, this function
returns the persistence pairs, where each simplex is replaced with the
vertex that gave it its filtration value.
Usage
SimplexTree$lower_star_persistence_generators()
Returns
A list with the following components:
A list of n x 2 integer matrices containing the regular persistence
pairs, grouped by dimension, with one vertex per extremity;
A list of m x ? integer matrices containing the essential features,
grouped by dimension, with one vertex each.
Method make_filtration_non_decreasing()
This function ensures that each simplex has a higher
filtration value than its faces by increasing the filtration values.
Usage
SimplexTree$make_filtration_non_decreasing(chainable = TRUE)
Arguments
chainableA boolean specifying whether the method should return the
class itself, hence allowing its use in pipe chaining. Defaults to TRUE,
which enables chaining.
Returns
The updated SimplexTree class itself invisibly if
chainable is set to TRUE (default behavior), or a boolean set to
TRUE if any filtration value was modified or to FALSE if the
filtration was already non-decreasing.
Method num_simplices()
This function returns the number of simplices of the
simplicial complex.
Usage
SimplexTree$num_simplices()
Returns
An integer value storing the number of simplices in the
simplicial complex.
Method num_vertices()
This function returns the number of vertices of the
simplicial complex.
Usage
SimplexTree$num_vertices()
Returns
An integer value storing the number of vertices in the simplicial
complex.
Method persistence()
This function computes and returns the persistence of the
simplicial complex.
Usage
SimplexTree$persistence(
homology_coeff_field = 11,
min_persistence = 0,
persistence_dim_max = FALSE
)
Arguments
homology_coeff_fieldAn integer value specifying the homology
coefficient field. Must be a prime number. Defaults to 11L. Maximum
is 46337L.
min_persistenceA numeric value specifying the minimum persistence
value to take into account (strictly greater than min_persistence).
Defaults to 0.0. Set min_persistence = -1.0 to see all values.
persistence_dim_maxA boolean specifying whether the persistent
homology for the maximal dimension in the complex is computed
(persistence_dim_max = TRUE). If FALSE, it is ignored. Defaults to
FALSE.
Returns
A tibble listing all persistence feature
summarised by 3 variables: dimension, birth and death.
Method persistence_intervals_in_dimension()
This function returns the persistence intervals of the
simplicial complex in a specific dimension.
Usage
SimplexTree$persistence_intervals_in_dimension(dimension)
Arguments
dimensionAn integer value specifying the desired dimension.
Returns
A tibble storing the persistence intervals
for the required dimension in two columns birth and death.
Method persistence_pairs()
This function returns a list of persistence birth and death
simplices pairs.
Usage
SimplexTree$persistence_pairs()
Returns
A list of pairs of integer vectors storing a list of persistence
simplices intervals.
Method persistent_betti_numbers()
This function returns the persistent Betti numbers of the
simplicial complex.
Usage
SimplexTree$persistent_betti_numbers(from_value, to_value)
Arguments
from_valueA numeric value specifying the persistence birth limit
to be added in the numbers (persistent birth <= from_value).
to_valueA numeric value specifying the persistence death limit to
be added in the numbers (persistent death > to_value).
Returns
An integer vector storing the persistent Betti numbers.
Method prune_above_filtration()
Prune above filtration value given as parameter.
Usage
SimplexTree$prune_above_filtration(filtration, chainable = TRUE)
Arguments
filtrationA numeric value specifying the maximum threshold value.
chainableA boolean specifying whether the method should return the
class itself, hence allowing its use in pipe chaining. Defaults to TRUE,
which enables chaining.
Details
Note that the dimension of the simplicial complex may be lower
after calling prune_above_filtration() than it was before. However,
upper_bound_dimension() will return the old value, which remains a
valid upper bound. If you care, you can call dimension() method to
recompute the exact dimension.
Returns
The updated SimplexTree class itself invisibly if
chainable is set to TRUE (default behavior), or a boolean set to
TRUE if the filtration has been modified or to FALSE otherwise.
Method remove_maximal_simplex()
This function removes a given maximal N-simplex from the
simplicial complex.
Usage
SimplexTree$remove_maximal_simplex(simplex)
Arguments
simplexAn integer vector representing the N-simplex in the form
of a list of vertices.
Details
The dimension of the simplicial complex may be lower after
calling $remove_maximal_simplex() than it was before. However,
$upper_bound_dimension() method will return the old value, which
remains a valid upper bound. If you care, you can call $dimension()
to recompute the exact dimension.
Returns
The updated SimplexTree class itself invisibly.
Method reset_filtration()
This function resets the filtration value of all the
simplices of dimension at least min_dim. Resets all the simplex tree
when min_dim = 0L. reset_filtration may break the filtration
property with min_dim > 0, and it is the user’s responsibility to
make it a valid filtration (using a large enough filtration value, or
calling $make_filtration_non_decreasing() afterwards for instance).
Usage
SimplexTree$reset_filtration(filtration, min_dim = 0)
Arguments
filtrationA numeric value specyfing the filtration threshold.
min_dimAn integer value specifying the minimal dimension.
Defaults to 0L.
Returns
The updated SimplexTree class itself invisibly.
Method set_dimension()
This function sets the dimension of the simplicial complex.
Usage
SimplexTree$set_dimension(dimension)
Arguments
dimensionAn integer value specifying the dimension.
Details
This function must be used with caution because it disables
dimension recomputation when required (this recomputation can be
triggered by $remove_maximal_simplex() or
$prune_above_filtration()).
Returns
The updated SimplexTree class itself invisibly.
Method upper_bound_dimension()
This function returns a valid dimension upper bound of the
simplicial complex.
Usage
SimplexTree$upper_bound_dimension()
Returns
An integer value storing an upper bound on the dimension of the
simplicial complex.
Method write_persistence_diagram()
This function writes the persistence intervals of the
simplicial complex in a user given file name.
Usage
SimplexTree$write_persistence_diagram(persistence_file)
Arguments
persistence_fileA string specifying the name of the file.
Returns
The updated SimplexTree class itself invisibly.
Method clone()
The objects of this class are cloneable with this method.
Usage
SimplexTree$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
Author(s)
Clément Maria
See Also
Other data structures for cell complexes:
CubicalComplex,
PeriodicCubicalComplex
Examples
st <- SimplexTree$new()
st
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$set_is_flag(TRUE)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$filtration(1)
st$assign_filtration(1, 0.8)
st$filtration(1)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$compute_persistence()$betti_numbers()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$collapse_edges()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$dimension()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$expansion(2)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$extend_filtration()
st$extended_persistence()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$filtration(0)
st$filtration(1:2)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$find(0)
X <- seq_circle(10)
rc <- RipsComplex$new(data = X, max_edge_length = 1)
st <- rc$create_simplex_tree(1)
st$compute_persistence()$flag_persistence_generators()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
splx <- st$get_simplices()$simplex[[1]]
st$get_boundaries(splx)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$get_cofaces(1:2, 0)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$get_filtration()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$get_simplices()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$get_skeleton(0)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$get_star(1:2)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$insert(1:2)
st$insert(1:3, chainable = FALSE)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$compute_persistence()$lower_star_persistence_generators()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$make_filtration_non_decreasing()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$num_simplices()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$num_vertices()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$persistence()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$compute_persistence()$persistence_intervals_in_dimension(1)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$compute_persistence()$persistence_pairs()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$compute_persistence()$persistent_betti_numbers(0, 0.1)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$prune_above_filtration(0.12)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$remove_maximal_simplex(1:2)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$reset_filtration(0.1)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$set_dimension(1)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$upper_bound_dimension()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
f <- fs::file_temp(ext = ".dgm")
st$compute_persistence()$write_persistence_diagram(f)
fs::file_delete(f)
rgudhi documentation built on March 31, 2023, 11:38 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| SimplexTree | R Documentation |
R6 Class for Simplex Tree
Description
The simplex tree is an efficient and flexible data structure for representing general (filtered) simplicial complexes. The data structure is described in \insertCiteboissonnat2014simplex;textualrgudhi.
Details
This class is a filtered, with keys, and non contiguous vertices version of the simplex tree.
References
\insertCitedSuper class
rgudhi::PythonClass -> SimplexTree
Methods
Public methods
Inherited methods
Method new()
The SimplexTree class constructor.
Usage
SimplexTree$new(py_class = NULL)
Arguments
py_classA Python
SimplexTreeclass object. Defaults toNULLwhich uses the Python class constructor instead.
Returns
A new SimplexTree object.
Method set_is_flag()
This function sets the internal field m_IsFlag which
records whether the simplex tree is a flag complex (i.e. has been
generated by a Rips complex).
Usage
SimplexTree$set_is_flag(val)
Arguments
valA boolean specifying whether the simplex tree is a flag complex.
Details
The SimplexTree class initializes the m_IsFlag
field to FALSE by default and this method specifically allows to
overwrite this default value.
Returns
The updated SimplexTree class itself invisibly.
Method assign_filtration()
This function assigns a new filtration value to a given N-simplex.
Usage
SimplexTree$assign_filtration(simplex, filtration)
Arguments
simplexAn integer vector representing the N-simplex in the form of a list of vertices.
filtrationA numeric value specifying the new filtration value.
Details
Beware that after this operation, the structure may not be a
valid filtration anymore, a simplex could have a lower filtration value
than one of its faces. Callers are responsible for fixing this (with
more calls to the $assign_filtration() method or a call to the
$make_filtration_non_decreasing() method for instance) before calling
any function that relies on the filtration property, such as
persistence().
Returns
The updated SimplexTree class itself invisibly.
Method betti_numbers()
This function returns the Betti numbers of the simplicial complex.
Usage
SimplexTree$betti_numbers()
Returns
An integer vector storing the Betti numbers.
Method collapse_edges()
Assuming the simplex tree is a 1-skeleton graph, this method
collapse edges (simplices of higher dimension are ignored) and resets
the simplex tree from the remaining edges. A good candidate is to build
a simplex tree on top of a RipsComplex of dimension 1 before
collapsing edges as done in this Python example.
For implementation details, please refer to
\insertCiteboissonnat2020edge;textualrgudhi.
Usage
SimplexTree$collapse_edges(nb_iterations = 1)
Arguments
nb_iterationsAn integer value specifying the number of edge collapse iterations to perform. Defaults to
1L.
Details
It requires Eigen >= 3.1.0 and an exception is thrown if not
available.
References
\insertCitedReturns
The updated SimplexTree class itself invisibly.
Method compute_persistence()
This function computes the persistence of the simplicial
complex, so it can be accessed through $persistent_betti_numbers(),
$persistence_pairs(), etc. This function is equivalent to
$persistence() when you do not want the list that $persistence()
returns.
Usage
SimplexTree$compute_persistence( homology_coeff_field = 11, min_persistence = 0, persistence_dim_max = FALSE )
Arguments
homology_coeff_fieldAn integer value specifying the homology coefficient field. Must be a prime number. Defaults to
11L. Maximum is46337L.min_persistenceA numeric value specifying the minimum persistence value to take into account (strictly greater than
min_persistence). Defaults to0.0. Setmin_persistence = -1.0to see all values.persistence_dim_maxA boolean specifying whether the persistent homology for the maximal dimension in the complex is computed (
persistence_dim_max = TRUE). IfFALSE, it is ignored. Defaults toFALSE.
Returns
The updated SimplexTree class itself invisibly.
Method dimension()
This function returns the dimension of the simplicial complex.
Usage
SimplexTree$dimension()
Details
This function is not constant time because it can recompute
dimension if required (can be triggered by $remove_maximal_simplex()
or $prune_above_filtration() methods for instance).
Returns
An integer value storing the simplicial complex dimension.
Method expansion()
Expands the simplex tree containing only its one skeleton
until dimension max_dim.
Usage
SimplexTree$expansion(max_dim)
Arguments
max_dimAn integer value specifying the maximal dimension to expented the simplex tree to.
Details
The expanded simplicial complex until dimension d attached to
a graph G is the maximal simplicial complex of dimension at most d
admitting the graph G as 1-skeleton. The filtration value assigned to
a simplex is the maximal filtration value of one of its edges.
The simplex tree must contain no simplex of dimension bigger than 1 when calling the method.
Returns
The updated SimplexTree class itself invisibly.
Method extend_filtration()
Extend filtration for computing extended persistence. This function only uses the filtration values at the 0-dimensional simplices, and computes the extended persistence diagram induced by the lower-star filtration computed with these values.
Usage
SimplexTree$extend_filtration()
Details
Note that after calling this function, the filtration values are
actually modified within the simplex tree. The method
$extended_persistence() retrieves the original values.
Note that this code creates an extra vertex internally, so you should
make sure that the simplex tree does not contain a vertex with the
largest possible value (i.e., 4294967295).
This notebook explains how to compute an extension of persistence called extended persistence.
Returns
The updated SimplexTree class itself invisibly.
Method extended_persistence()
This function retrieves good values for extended persistence, and separate the diagrams into the Ordinary, Relative, Extended+ and Extended- subdiagrams.
Usage
SimplexTree$extended_persistence( homology_coeff_field = 11, min_persistence = 0 )
Arguments
homology_coeff_fieldAn integer value specifying the homology coefficient field. Must be a prime number. Defaults to
11L. Maximum is46337L.min_persistenceA numeric value specifying the minimum persistence value to take into account (strictly greater than
min_persistence). Defaults to0.0. Setmin_persistence = -1.0to see all values.
Details
The coordinates of the persistence diagram points might be a
little different than the original filtration values due to the
internal transformation (scaling to [-2,-1]) that is performed on these
values during the computation of extended persistence.
This notebook explains how to compute an extension of persistence called extended persistence.
Returns
A list of four persistence diagrams in the format described in
$persistence(). The first one is Ordinary, the second one is
Relative, the third one is Extended+ and the fourth one is
Extended-. See this
article
and/or Section 2.2 in this
article
for a description of these subtypes.
Method filtration()
This function returns the filtration value for a given N-simplex in this simplicial complex, or +infinity if it is not in the complex.
Usage
SimplexTree$filtration(simplex)
Arguments
simplexAn integer vector representing the N-simplex in the form of a list of vertices.
Returns
A numeric value storing the filtration value for the input N-simplex.
Method find()
This function returns if the N-simplex was found in the simplicial complex or not.
Usage
SimplexTree$find(simplex)
Arguments
simplexAn integer vector representing the N-simplex in the form of a list of vertices.
Returns
A boolean storing whether the input N-simplex was found in the simplicial complex.
Method flag_persistence_generators()
Assuming this is a flag complex, this function returns the persistence pairs, where each simplex is replaced with the vertices of the edges that gave it its filtration value.
Usage
SimplexTree$flag_persistence_generators()
Returns
A list with the following components:
An
n x 3integer matrix containing the regular persistence pairs of dimension 0, with one vertex for birth and two for death;A list of
m x 4integer matrices containing the other regular persistence pairs, grouped by dimension, with 2 vertices per extremity;An
l x ?integer matrix containing the connected components, with one vertex each;A list of
k x 2integer matrices containing the other essential features, grouped by dimension, with 2 vertices for birth.
Method get_boundaries()
For a given N-simplex, this function returns a list of simplices of dimension N-1 corresponding to the boundaries of the N-simplex.
Usage
SimplexTree$get_boundaries(simplex)
Arguments
simplexAn integer vector representing the N-simplex in the form of a list of vertices.
Returns
A tibble listing the (simplicies of the)
boundary of the input N-simplex in column simplex along with their
corresponding filtration value in column filtration.
Method get_cofaces()
This function returns the cofaces of a given N-simplex with a given codimension.
Usage
SimplexTree$get_cofaces(simplex, codimension)
Arguments
simplexAn integer vector representing the N-simplex in the form of a list of vertices.
codimensionAn integer value specifying the codimension. If
codimension = 0, all cofaces are returned (equivalent of$get_star()function).
Returns
A tibble listing the (simplicies of the)
cofaces of the input N-simplex in column simplex along with their
corresponding filtration value in column filtration.
Method get_filtration()
This function retrieves the list of simplices and their given filtration values sorted by increasing filtration values.
Usage
SimplexTree$get_filtration()
Returns
A tibble listing the simplicies in column
simplex along with their corresponding filtration value in column
filtration, in increasing order of filtration value.
Method get_simplices()
This function retrieves the list of simplices and their given filtration values.
Usage
SimplexTree$get_simplices()
Returns
A tibble listing the simplicies in column
simplex along with their corresponding filtration value in column
filtration, in increasing order of filtration value.
Method get_skeleton()
This function returns a generator with the (simplices of the) skeleton of a maximum given dimension.
Usage
SimplexTree$get_skeleton(dimension)
Arguments
dimensionA integer value specifying the skeleton dimension value.
Returns
A tibble listing the (simplicies of the)
skeleton of a maximum dimension in column simplex along with their
corresponding filtration value in column filtration.
Method get_star()
This function returns the star of a given N-simplex.
Usage
SimplexTree$get_star(simplex)
Arguments
simplexAn integer vector representing the N-simplex in the form of a list of vertices.
Returns
A tibble listing the (simplicies of the)
star of a simplex in column simplex along with their corresponding
filtration value in column filtration.
Method insert()
This function inserts the given N-simplex and its subfaces with the given filtration value. If some of those simplices are already present with a higher filtration value, their filtration value is lowered.
Usage
SimplexTree$insert(simplex, filtration = 0, chainable = TRUE)
Arguments
simplexAn integer vector representing the N-simplex in the form of a list of vertices.
filtrationA numeric value specifying the filtration value of the simplex. Defaults to
0.0.chainableA boolean specifying whether the method should return the class itself, hence allowing its use in pipe chaining. Defaults to
TRUE, which enables chaining.
Returns
The updated SimplexTree class itself invisibly if
chainable is set to TRUE (default behavior), or a boolean set to
TRUE if the simplex was not yet in the complex or FALSE otherwise
(whatever its original filtration value).
Method lower_star_persistence_generators()
Assuming this is a lower-star filtration, this function returns the persistence pairs, where each simplex is replaced with the vertex that gave it its filtration value.
Usage
SimplexTree$lower_star_persistence_generators()
Returns
A list with the following components:
A list of
n x 2integer matrices containing the regular persistence pairs, grouped by dimension, with one vertex per extremity;A list of
m x ?integer matrices containing the essential features, grouped by dimension, with one vertex each.
Method make_filtration_non_decreasing()
This function ensures that each simplex has a higher filtration value than its faces by increasing the filtration values.
Usage
SimplexTree$make_filtration_non_decreasing(chainable = TRUE)
Arguments
chainableA boolean specifying whether the method should return the class itself, hence allowing its use in pipe chaining. Defaults to
TRUE, which enables chaining.
Returns
The updated SimplexTree class itself invisibly if
chainable is set to TRUE (default behavior), or a boolean set to
TRUE if any filtration value was modified or to FALSE if the
filtration was already non-decreasing.
Method num_simplices()
This function returns the number of simplices of the simplicial complex.
Usage
SimplexTree$num_simplices()
Returns
An integer value storing the number of simplices in the simplicial complex.
Method num_vertices()
This function returns the number of vertices of the simplicial complex.
Usage
SimplexTree$num_vertices()
Returns
An integer value storing the number of vertices in the simplicial complex.
Method persistence()
This function computes and returns the persistence of the simplicial complex.
Usage
SimplexTree$persistence( homology_coeff_field = 11, min_persistence = 0, persistence_dim_max = FALSE )
Arguments
homology_coeff_fieldAn integer value specifying the homology coefficient field. Must be a prime number. Defaults to
11L. Maximum is46337L.min_persistenceA numeric value specifying the minimum persistence value to take into account (strictly greater than
min_persistence). Defaults to0.0. Setmin_persistence = -1.0to see all values.persistence_dim_maxA boolean specifying whether the persistent homology for the maximal dimension in the complex is computed (
persistence_dim_max = TRUE). IfFALSE, it is ignored. Defaults toFALSE.
Returns
A tibble listing all persistence feature
summarised by 3 variables: dimension, birth and death.
Method persistence_intervals_in_dimension()
This function returns the persistence intervals of the simplicial complex in a specific dimension.
Usage
SimplexTree$persistence_intervals_in_dimension(dimension)
Arguments
dimensionAn integer value specifying the desired dimension.
Returns
A tibble storing the persistence intervals
for the required dimension in two columns birth and death.
Method persistence_pairs()
This function returns a list of persistence birth and death simplices pairs.
Usage
SimplexTree$persistence_pairs()
Returns
A list of pairs of integer vectors storing a list of persistence simplices intervals.
Method persistent_betti_numbers()
This function returns the persistent Betti numbers of the simplicial complex.
Usage
SimplexTree$persistent_betti_numbers(from_value, to_value)
Arguments
from_valueA numeric value specifying the persistence birth limit to be added in the numbers (
persistent birth <= from_value).to_valueA numeric value specifying the persistence death limit to be added in the numbers (
persistent death > to_value).
Returns
An integer vector storing the persistent Betti numbers.
Method prune_above_filtration()
Prune above filtration value given as parameter.
Usage
SimplexTree$prune_above_filtration(filtration, chainable = TRUE)
Arguments
filtrationA numeric value specifying the maximum threshold value.
chainableA boolean specifying whether the method should return the class itself, hence allowing its use in pipe chaining. Defaults to
TRUE, which enables chaining.
Details
Note that the dimension of the simplicial complex may be lower
after calling prune_above_filtration() than it was before. However,
upper_bound_dimension() will return the old value, which remains a
valid upper bound. If you care, you can call dimension() method to
recompute the exact dimension.
Returns
The updated SimplexTree class itself invisibly if
chainable is set to TRUE (default behavior), or a boolean set to
TRUE if the filtration has been modified or to FALSE otherwise.
Method remove_maximal_simplex()
This function removes a given maximal N-simplex from the simplicial complex.
Usage
SimplexTree$remove_maximal_simplex(simplex)
Arguments
simplexAn integer vector representing the N-simplex in the form of a list of vertices.
Details
The dimension of the simplicial complex may be lower after
calling $remove_maximal_simplex() than it was before. However,
$upper_bound_dimension() method will return the old value, which
remains a valid upper bound. If you care, you can call $dimension()
to recompute the exact dimension.
Returns
The updated SimplexTree class itself invisibly.
Method reset_filtration()
This function resets the filtration value of all the
simplices of dimension at least min_dim. Resets all the simplex tree
when min_dim = 0L. reset_filtration may break the filtration
property with min_dim > 0, and it is the user’s responsibility to
make it a valid filtration (using a large enough filtration value, or
calling $make_filtration_non_decreasing() afterwards for instance).
Usage
SimplexTree$reset_filtration(filtration, min_dim = 0)
Arguments
filtrationA numeric value specyfing the filtration threshold.
min_dimAn integer value specifying the minimal dimension. Defaults to
0L.
Returns
The updated SimplexTree class itself invisibly.
Method set_dimension()
This function sets the dimension of the simplicial complex.
Usage
SimplexTree$set_dimension(dimension)
Arguments
dimensionAn integer value specifying the dimension.
Details
This function must be used with caution because it disables
dimension recomputation when required (this recomputation can be
triggered by $remove_maximal_simplex() or
$prune_above_filtration()).
Returns
The updated SimplexTree class itself invisibly.
Method upper_bound_dimension()
This function returns a valid dimension upper bound of the simplicial complex.
Usage
SimplexTree$upper_bound_dimension()
Returns
An integer value storing an upper bound on the dimension of the simplicial complex.
Method write_persistence_diagram()
This function writes the persistence intervals of the simplicial complex in a user given file name.
Usage
SimplexTree$write_persistence_diagram(persistence_file)
Arguments
persistence_fileA string specifying the name of the file.
Returns
The updated SimplexTree class itself invisibly.
Method clone()
The objects of this class are cloneable with this method.
Usage
SimplexTree$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
Author(s)
Clément Maria
See Also
Other data structures for cell complexes:
CubicalComplex,
PeriodicCubicalComplex
Examples
st <- SimplexTree$new()
st
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$set_is_flag(TRUE)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$filtration(1)
st$assign_filtration(1, 0.8)
st$filtration(1)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$compute_persistence()$betti_numbers()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$collapse_edges()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$dimension()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$expansion(2)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$extend_filtration()
st$extended_persistence()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$filtration(0)
st$filtration(1:2)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$find(0)
X <- seq_circle(10)
rc <- RipsComplex$new(data = X, max_edge_length = 1)
st <- rc$create_simplex_tree(1)
st$compute_persistence()$flag_persistence_generators()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
splx <- st$get_simplices()$simplex[[1]]
st$get_boundaries(splx)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$get_cofaces(1:2, 0)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$get_filtration()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$get_simplices()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$get_skeleton(0)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$get_star(1:2)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$insert(1:2)
st$insert(1:3, chainable = FALSE)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$compute_persistence()$lower_star_persistence_generators()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$make_filtration_non_decreasing()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$num_simplices()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$num_vertices()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$persistence()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$compute_persistence()$persistence_intervals_in_dimension(1)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$compute_persistence()$persistence_pairs()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$compute_persistence()$persistent_betti_numbers(0, 0.1)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$prune_above_filtration(0.12)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$remove_maximal_simplex(1:2)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$reset_filtration(0.1)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$set_dimension(1)
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
st$upper_bound_dimension()
X <- seq_circle(10)
ac <- AlphaComplex$new(points = X)
st <- ac$create_simplex_tree()
f <- fs::file_temp(ext = ".dgm")
st$compute_persistence()$write_persistence_diagram(f)
fs::file_delete(f)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.