Filtration: A filtered sequence of complexes¶
- class simplicial.Filtration(ind=0, rep=None)¶
A filtration of simplicial complexes.
A filtration is a sequence of simplicial complexes parameterised by a single index (typically a number) and ordered by inclusion. For two values of the index \(p_1\) and \(p_2\) with corresponding complexes \(C_1\) and \(C_2\), \(p_1 < p_2 \implies C_1 < C_2\): all the simplices in \(C_1\) are contained in \(C_2\), with both being legal simplicial complexes.
This class allows different simplices to be assigned to different indices while maintaining the integrity of the complex. It provides a method for copying just the complex at a given level if required.
Filtrations are the basis for persistent homology, and this class also provides operations for efficiently computing the homology groups of the sequence of complexes.
- Parameters
ind (
int) – (optional) the initial index (defaults to 0)rep (
Optional[Any]) – (optional) the representation being used
Building the filtration¶
Filtrations are built in the same way as ordinary complexes, by adding (and possibly deleting) simplices. The main difference is simplices are added to a filtration at a specific index, with the complex associated with each index growing as the index grows.
- Filtration.addSimplex(fs=[], id=None, attr=None)¶
Add a simplex to the filtration at the current index.
- Parameters
fs (
Set[Any]) – (optional) a list of faces of the simplexid (
Optional[Any]) – (optional) name for the simplexattr (
Optional[Dict[str,Any]]) – (optional) dict of attributes
- Return type
Any- Returns
the name of the new simplex
The index is managed by selecting the appropriate value for the filtration.
- Filtration.getIndex()¶
Get the current index.
- Return type
int- Returns
the index
- Filtration.setIndex(ind)¶
Set the index.
- Parameters
ind (
int) – the new index value
- Filtration.setPreviousIndex()¶
Set the index to the previous value. If we’re at the smallest index, nothing happens.
- Returns
the new index
- Filtration.setNextIndex()¶
Set the index to the next value. If we’re at the largest index, nothing happens.
- Returns
the new index
- Filtration.setMinimumIndex()¶
Set the index of the filtration to its minumum value, selecting the smallest complex.
- Filtration.setMaximumIndex()¶
Set the index of the filtration to its maximum value, selecting the largest complex.
- Filtration.indices(reverse=False)¶
Return an enumeration of the indices of the filtration, in ascending order by default.
- Parameters
reverse (
bool) – (optional) reverse the order of the indices (defaults to ascending)- Return type
Iterable[int]- Returns
the indices
- Filtration.isIndex(ind, fatal=False)¶
True is the given value is an index in this filtration.
- Parameters
ind (
int) – the indexfatal (
bool) – (optional) make a non-index fatal (defaults to False)
- Return type
bool- Returns
True if the index appears in this filtration
Copying the filtration¶
Filtrations can be freely copied, either completely or by extracting the simplicial complex equivalent to the filtration at its current index.
- Filtration.copy(c=None)¶
Return a copy of this filtration, maintaining the indexing.
- Parameters
c (
Optional[Filtration]) – (optional) the filtration to copy into (defaults to a new filtration)- Return type
- Returns
a copy of this filtration
- Filtration.snap(c=None)¶
Return a snapshot of the complex at the current index. This returns a single simplicial complex, not a filtration as returned by
copy(). The complexes corresponding to all, indices can be retrieved usingcomplexes().- Parameters
c (
Optional[SimplicialComplex]) – (optional) the complex to copy to (defaults to a new complex)- Return type
- Returns
a complex built from the filtration at this index
Accessing the filtration¶
The filtration can be accessed using all the normal methods of a simplicial complex. All the operations occur relative to the current index of the filtration.
- Filtration.containsSimplex(s)¶
Test whether the filtration contains the given simplex at the current index. This implies that the simplex was added to the filtration at an index that is the same or lessa than the current index.
- Return type
bool- Returns
True if the simplex is in the filtration
- Filtration.orderOf(s)¶
Return the order of the simplex in the filtration. This will raise an exception if the simplex isn’t defined at the current index.
- Parameters
s (
Any) – the simplex- Return type
int- Returns
the order of the simplex
- Filtration.indexOf(s)¶
Return the index of the simplex in the filtration. This will raise an exception if the simplex isn’t defined at the current index.
- Parameters
s – the simplex
- Returns
the index of the simplex within its order
- Filtration.simplices(reverse=False)¶
Return all the simplices in the filtration at the current index. The simplices are returned in order of their orders, 0-simplices first unless the reverse paarneter is True, in which case 0-simplices will be last.
- Parameters
reverse (
bool) – (optional) reverse sort order (defaults to False)- Return type
Iterable[Any]- Returns
a list of simplices
- Filtration.numberOfSimplices()¶
Return the number of simplices in the filtration up to and including the current index.
- Return type
int- Returns
the number of simplices
- Filtration.numberOfSimplicesOfOrder()¶
Return a dict mapping an order to the number of simplices of that order in the filtratrion up to and including the current index.
- Return type
List[int]- Returns
a list of number of simplices at each order
It is also possible to examine the structure of the filtration as it is constructed, by looking at the indexed complexes individually or by examining the simplices added at each index.
- Filtration.simplicesAddedAtIndex(ind, reverse=False)¶
Return all the simplices added at the given index. By default the simplices are returned in increasing order of order, 0-simplices first.
- Parameters
ind (
int) – the indexreverse – (optional) reverse sort order (defaults to False)
- Return type
Set[Any]- Returns
the simplices
- Filtration.addedAtIndex(s)¶
Return the index at which the given simplex was added to the filtration. When the index is considered as representing time this is sometimes called the “birth time” for the simplex.
- Parameters
s – the simplex
- Returns
the index