Loading...
Searching...
No Matches
Gudhi::zigzag_persistence::Filtered_zigzag_persistence_with_storage< FilteredZigzagOptions > Class Template Reference
Zigzag Persistence

Class computing the zigzag persistent homology of a zigzag filtration. Algorithm based on [zigzag]. 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.
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.
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.
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.
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.
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.
std::vector< Filtration_value_interval > | get_persistence_diagram (Filtration_value shortestInterval=0., bool includeInfiniteBars=true)
| Returns the current persistence diagram.

## 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 [zigzag]. 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>
filtered_zigzag_persistence.h
Contains the implementation of the Gudhi::zigzag_persistence::Default_filtered_zigzag_options structu...

#### Useful aliases

using Filtered_zigzag_persistence_with_storage = Gudhi::zigzag_persistence::Filtered_zigzag_persistence_with_storage<>;
Gudhi::zigzag_persistence::Filtered_zigzag_persistence_with_storage
Class computing the zigzag persistent homology of a zigzag filtration. Algorithm based on zigzag....
Definition filtered_zigzag_persistence.h:121
Gudhi::zigzag_persistence::Filtered_zigzag_persistence_with_storage::Filtered_zigzag_persistence_with_storage
Filtered_zigzag_persistence_with_storage(unsigned int preallocationSize=0, int ignoreCyclesAboveDim=-1)
Constructor.
Definition filtered_zigzag_persistence.h:152

#### 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);
Gudhi::zigzag_persistence::Filtered_zigzag_persistence_with_storage::remove_cell
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 ...
Definition filtered_zigzag_persistence.h:221
Gudhi::zigzag_persistence::Filtered_zigzag_persistence_with_storage::insert_cell
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.
Definition filtered_zigzag_persistence.h:180

#### 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;
}
Gudhi::zigzag_persistence::Filtered_zigzag_persistence_with_storage::get_persistence_diagram
std::vector< Filtration_value_interval > get_persistence_diagram(Filtration_value shortestInterval=0., bool includeInfiniteBars=true)
Returns the current persistence diagram.
Definition filtered_zigzag_persistence.h:286

Template Parameters

  FilteredZigzagOptions | Structure following the FilteredZigzagOptions concept. Default value: Default_filtered_zigzag_options.

Examples
  example_usage_filtered_zigzag_persistence_with_storage.cpp, and example_zigzag_filtration_as_input_loop.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.

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