Gudhi::zigzag_persistence::Filtered_zigzag_persistence_with_storage< FilteredZigzagOptions > Class Template Reference

Class computing the zigzag persistent homology of a zigzag filtration. Algorithm based on [41]. Even though the insertions and removals are given in a "stream-like" way, the barcode and other values are stored during the whole process and not removed. It is therefore suited for smaller filtrations where the clean ups produce a higher overhead than the memory consumption. More...

#include <include/gudhi/filtered_zigzag_persistence.h>

Public Types
using	Options = FilteredZigzagOptions
using	Internal_key = typename Options::Internal_key
using	Cell_key = typename Options::Cell_key
using	Filtration_value = typename Options::Filtration_value
using	Dimension = typename Options::Dimension
using	Index_interval = Gudhi::persistence_matrix::Persistence_interval< Dimension, Internal_key >
	Persistence index interval type.
using	Filtration_value_interval = Gudhi::persistence_matrix::Persistence_interval< Dimension, Filtration_value >
	Persistence filtration interval type.

Public Member Functions
	Filtered_zigzag_persistence_with_storage (unsigned int preallocationSize=0, int ignoreCyclesAboveDim=-1)
	Constructor. More...
template<class BoundaryRange = std::initializer_list<Cell_key>>
Internal_key	insert_cell (Cell_key cellID, const BoundaryRange &boundary, Dimension dimension, Filtration_value filtrationValue)
	Updates the zigzag persistence diagram after the insertion of the given cell. More...
Internal_key	remove_cell (Cell_key cellID, Filtration_value filtrationValue)
	Updates the zigzag persistence diagram after the removal of the given cell if the cell was contained in the current complex (note that it will not contain cells of dimension > ignoreCyclesAboveDim if the latter was non negative at construction of the class). Otherwise, just increases the operation count by one. More...
Internal_key	apply_identity ()
	To use when a cell is neither inserted nor removed, but the filtration moves along the identity operator on homology level. Useful to keep the birth/death indices aligned when insertions/removals are purposely skipped to avoid useless computation. More...
const std::vector< Index_interval > &	get_index_persistence_diagram () const
	Returns the "index persistence diagram" of the current filtration, that is, the pairs of atomic arrow numbers corresponding to a birth-death pair. Does not contain points at infinity, only the cycle classes which already died are represented. More...
Filtration_value	get_filtration_value_from_index (Internal_key idx)
	Returns the filtration value $f(idx)$ associated to the index $idx$ returned by get_index_persistence_diagram. More...
std::vector< Filtration_value_interval >	get_persistence_diagram (Filtration_value shortestInterval=0., bool includeInfiniteBars=true)
	Returns the current persistence diagram. More...

Detailed Description

template<class FilteredZigzagOptions = Default_filtered_zigzag_options>
class Gudhi::zigzag_persistence::Filtered_zigzag_persistence_with_storage< FilteredZigzagOptions >

Class computing the zigzag persistent homology of a zigzag filtration. Algorithm based on [41]. Even though the insertions and removals are given in a "stream-like" way, the barcode and other values are stored during the whole process and not removed. It is therefore suited for smaller filtrations where the clean ups produce a higher overhead than the memory consumption.

After construction of the class, the zigzag filtration should be given in a streaming like way, i.e., call insert_cell, remove_cell or apply_identity for each step of the filtration in order of the filtration. To retrieve the current persistence diagram at any moment of the filtration, use get_persistence_diagram or get_index_persistence_diagram.

Minimalistic example of usage

Includes

#include <gudhi/filtered_zigzag_persistence.h>

Useful aliases

using Filtered_zigzag_persistence_with_storage = Gudhi::zigzag_persistence::Filtered_zigzag_persistence_with_storage<>;

Construction with default values

Filtered_zigzag_persistence_with_storage zp;

Input of the zigzag sequence/filtration

// In all cases, it is important that the operations of insertions and removals are made **in the same order**
// as in the zigzag filtration ones wants to compute the barcode from.
 
// A cell can be identified in the boundaries by any given numerical label, it is just important that the given
// filtration values are monotonous (ie., either only increasing or only decreasing).
 
//inserts vertex 2 at filtration value 0.1 -> birth at 0.1 of 0-cycle
zp.insert_cell(2, {}, 0, 0.1);
//inserts vertex 4 at filtration value 0.1 -> birth at 0.1 of 0-cycle
zp.insert_cell(4, {}, 0, 0.1);
//inserts edge 5 = (2,4) at filtration value 0.3 -> death at 0.3 -> outputs/stores (0, 0.1, 0.3)
zp.insert_cell(5, {2, 4}, 1, 0.3);
//inserts vertex 3 at filtration value 0.4 -> birth at 0.4 of 0-cycle
zp.insert_cell(3, {}, 0, 0.4);
//inserts edge 6 = (2,3) at filtration value 0.4 -> death at 0.4 of the cycle born at 0.4 -> outputs/stores nothing
zp.insert_cell(6, {2, 3}, 1, 0.4);
//inserts edge 9 = (3,4) at filtration value 1.2 -> birth at 1.2 of 1-cycle
zp.insert_cell(9, {4, 3}, 1, 1.2);
//removes edge 6 at filtration value 1.5 -> death at 1.5 -> outputs/stores (1, 1.2, 1.5)
zp.remove_cell(6, 1.5);
//removes edge 5 at filtration value 2.0 -> birth at 2.0 of 0-cycle
zp.remove_cell(5, 2.0);

Finalizations

// The bars are stored within the class and where not output at all for now.
 
//get all bars in a vector
auto barcode = zp.get_persistence_diagram();
 
//do something with the vector, e.g., stream out content:
for (auto& bar : barcode) {
  std::cout << bar << std::endl;
}

Template Parameters

FilteredZigzagOptions

Structure following the FilteredZigzagOptions concept. Default value: Default_filtered_zigzag_options.

Examples

example_usage_filtered_zigzag_persistence_with_storage.cpp, example_zigzag_filtration_as_input_loop.cpp, and example_zzfiltration_from_file.cpp.

Member Typedef Documentation

Cell_key

template<class FilteredZigzagOptions = Default_filtered_zigzag_options>

using Gudhi::zigzag_persistence::Filtered_zigzag_persistence_with_storage< FilteredZigzagOptions >::Cell_key = typename Options::Cell_key

Cell ID type from external inputs.

Examples

example_zigzag_filtration_as_input_loop.cpp, and example_zzfiltration_from_file.cpp.

Dimension

template<class FilteredZigzagOptions = Default_filtered_zigzag_options>

using Gudhi::zigzag_persistence::Filtered_zigzag_persistence_with_storage< FilteredZigzagOptions >::Dimension = typename Options::Dimension

Type for dimension values.

Examples

example_zzfiltration_from_file.cpp.

Filtration_value

template<class FilteredZigzagOptions = Default_filtered_zigzag_options>

using Gudhi::zigzag_persistence::Filtered_zigzag_persistence_with_storage< FilteredZigzagOptions >::Filtration_value = typename Options::Filtration_value

Type for filtration values.

Examples

example_zigzag_filtration_as_input_loop.cpp, and example_zzfiltration_from_file.cpp.

Internal_key

template<class FilteredZigzagOptions = Default_filtered_zigzag_options>

using Gudhi::zigzag_persistence::Filtered_zigzag_persistence_with_storage< FilteredZigzagOptions >::Internal_key = typename Options::Internal_key

Key and index type, has to be signed.

Options

template<class FilteredZigzagOptions = Default_filtered_zigzag_options>

using Gudhi::zigzag_persistence::Filtered_zigzag_persistence_with_storage< FilteredZigzagOptions >::Options = FilteredZigzagOptions

Zigzag options.

Constructor & Destructor Documentation

Filtered_zigzag_persistence_with_storage()

template<class FilteredZigzagOptions = Default_filtered_zigzag_options>

Gudhi::zigzag_persistence::Filtered_zigzag_persistence_with_storage< FilteredZigzagOptions >::Filtered_zigzag_persistence_with_storage ( unsigned int  preallocationSize = 0, int  ignoreCyclesAboveDim = -1  )

inline

Constructor.

After construction of the class, the zigzag filtration should be given in a streaming like way, i.e., call insert_cell, remove_cell or apply_identity for each step of the filtration in order of the filtration. To retrieve the current persistence diagram at any moment of the filtration, use get_persistence_diagram or get_index_persistence_diagram.

Parameters

preallocationSize	Reserves space for preallocationSize cells in the internal data structure. This is optional and just helps skip a few reallocations. The optimal value (no reallocation, no wasted space) is the number of cells in the biggest complex of the filtration. Default value: 0.
ignoreCyclesAboveDim	Ignores cycles in dimension larger or equal in the final diagram. If -1, no cycles are ignored. Default value: -1.

Member Function Documentation

apply_identity()

template<class FilteredZigzagOptions = Default_filtered_zigzag_options>

Internal_key Gudhi::zigzag_persistence::Filtered_zigzag_persistence_with_storage< FilteredZigzagOptions >::apply_identity ( )

inline

To use when a cell is neither inserted nor removed, but the filtration moves along the identity operator on homology level. Useful to keep the birth/death indices aligned when insertions/removals are purposely skipped to avoid useless computation.

Returns

Number of the operation.

get_filtration_value_from_index()

template<class FilteredZigzagOptions = Default_filtered_zigzag_options>

Filtration_value Gudhi::zigzag_persistence::Filtered_zigzag_persistence_with_storage< FilteredZigzagOptions >::get_filtration_value_from_index ( Internal_key  idx )

inline

Returns the filtration value $f(idx)$ associated to the index $idx$ returned by get_index_persistence_diagram.

Parameters

idx	Birth or death index

Returns

Filtration_value Filtration value associated to idx.

get_index_persistence_diagram()

template<class FilteredZigzagOptions = Default_filtered_zigzag_options>

const std::vector< Index_interval > & Gudhi::zigzag_persistence::Filtered_zigzag_persistence_with_storage< FilteredZigzagOptions >::get_index_persistence_diagram ( ) const

inline

Returns the "index persistence diagram" of the current filtration, that is, the pairs of atomic arrow numbers corresponding to a birth-death pair. Does not contain points at infinity, only the cycle classes which already died are represented.

Returns

Reference to the list of intervals.

Examples

example_zigzag_filtration_as_input_loop.cpp.

get_persistence_diagram()

template<class FilteredZigzagOptions = Default_filtered_zigzag_options>

std::vector< Filtration_value_interval > Gudhi::zigzag_persistence::Filtered_zigzag_persistence_with_storage< FilteredZigzagOptions >::get_persistence_diagram ( Filtration_value  shortestInterval = 0., bool  includeInfiniteBars = true  )

inline

Returns the current persistence diagram.

Parameters

shortestInterval	Threshold. Every bar shorter than the given value will not be returned. Default value: 0.
includeInfiniteBars	If set to true, infinite bars are included in the diagram. Default value: true.

Returns

A vector of pairs of filtration values representing the persistence diagram.

Examples

example_zigzag_filtration_as_input_loop.cpp.

insert_cell()

template<class FilteredZigzagOptions = Default_filtered_zigzag_options>

template<class BoundaryRange = std::initializer_list<Cell_key>>

Internal_key Gudhi::zigzag_persistence::Filtered_zigzag_persistence_with_storage< FilteredZigzagOptions >::insert_cell ( Cell_key  cellID, const BoundaryRange &  boundary, Dimension  dimension, Filtration_value  filtrationValue  )

inline

Updates the zigzag persistence diagram after the insertion of the given cell.

Template Parameters

BoundaryRange

Range type needing size, begin and end members.

Parameters

cellID	ID representing the inserted cell.
boundary	Boundary of the inserted cell. The range should be composed of the IDs of all cells contained in the boundary (i.e. with non-zero coefficients), using the ID specified as cellID when the corresponding cell was previously inserted (recall that the cells should be inserted in order of filtration).
dimension	Dimension of the inserted cell.
filtrationValue	Filtration value associated to the cell. Assumed to be always larger or equal to previously used filtration values or always smaller or equal than previous values, ie. the changes are monotonous.

Returns

Number of the operation.

Examples

example_zigzag_filtration_as_input_loop.cpp, and example_zzfiltration_from_file.cpp.

remove_cell()

template<class FilteredZigzagOptions = Default_filtered_zigzag_options>

Internal_key Gudhi::zigzag_persistence::Filtered_zigzag_persistence_with_storage< FilteredZigzagOptions >::remove_cell ( Cell_key  cellID, Filtration_value  filtrationValue  )

inline

Updates the zigzag persistence diagram after the removal of the given cell if the cell was contained in the current complex (note that it will not contain cells of dimension > ignoreCyclesAboveDim if the latter was non negative at construction of the class). Otherwise, just increases the operation count by one.

Parameters

cellID	ID representing the cell to remove. Should be the same than the one used to insert it.
filtrationValue	Filtration value associated to the removal. Assumed to be always larger or equal to previously used filtration values or always smaller or equal than previous values, ie. the changes are monotonous.

Returns

Number of the operation.

Examples

example_zigzag_filtration_as_input_loop.cpp.

---

The documentation for this class was generated from the following file:

• include/gudhi/filtered_zigzag_persistence.h