==============
Major Features and Improvements
-------------------------------
This is a major release. The whole library has been fully refactored and all functions have been renamed. In particular:
- All functions have been split into an ``unweighted`` and a ``weighted`` version.
- The ``unweighted`` functions process unweighted graphs. In the adjacency matrices passed to them, off-diagonal, ``0`` or ``False`` values denote absent edges while non-``0`` or ``True`` values denote edges which are present. Diagonal values are ignored.
- The ``weighted`` functions process weighted graphs. In the adjacency matrices passed to them, the way zero values are handled depends on the format of the matrix. If the matrix is a dense ``numpy.ndarray``, zero values denote zero-weighted edges. If the matrix is a sparse ``scipy.sparse`` matrix, explicitly stored off-diagonal zeros and all diagonal zeros denote zero-weighted edges. Off-diagonal values that have not been explicitely stored are treated by ``scipy.sparse`` as zeros but will be understood as infinitely-valued edges, i.e., edges absent from the filtration. Diagonal elements are vertex weights.
- ``saveflag`` has been split into ``save_unweighted_flag`` and a ``save_weighted_flag``:
- ``save_unweighted_flag`` focuses on saving adjacency matrices of unweighted graphs into a `.flag` file understandable by C++ `flagser`.
- ``save_weighted_flag`` focuses on saving adjacency matrices of weighted graphs into a `.flag` file understandable by C++ `flagser`. It now takes a ``max_edge_weight`` argument. All edge weights greater than that value will be considered as infinitely-valued, i.e., absent from the filtration.
- ``loadflag`` has been split into ``load_unweighted_flag`` and a ``load_weighted_flag``.
- ``load_unweighted_flag`` focuses on loading ``.flag`` files as adjacency matrices of unweighted graphs.
- ``load_weighted_flag`` focuses on loading ``.flag`` files as adjacency matrices of weighted graphs. It now take an ``infinity_value`` parameter which is the value to use to denote an absence of edge. It is only useful when the output adjacency matrix is set to be a ``numpy.ndarray`` by passing `fmt` as ``'dense'``. If ``None``, it is set to the maximum value allowed by the passed `dtype`.
- ``flagser`` has been split into ``flagser_unweighted`` and a ``flagser_weighted``.
- ``flagser_unweighted`` focuses on the computation of homology and outputs Betti numbers, cell counts per dimension, and Euler characteristic.
- ``flagser_weighted`` focuses on the computation of persistent homology and outputs persistence diagrams, Betti numbers, cell counts per dimension, and Euler characteristic. It now takes a ``max_edge_weight`` argument. All edge weights greater than that value will be considered as infinitely-valued, i.e., absent from the filtration.
Additionally,
- The documentation have been strongly improved both in docstrings and in the code.
- The handling of default parameters has been improved and warnings are now issued.
- Sparse matrix efficiency warnings have been turned off (``lil_matrix`` cannot be used because it ignores explicitly set 0 values).
- Core functions to transform an adjacency matrix into the data structures understood by C++ ``flagser`` have been moved to the new ``_utils.py``.
- Tests have been extended according to cover the new functionalities.
Bug Fixes
---------
The following bug fixes were introduced:
- A bug fix from C++ ``flagser`` on ``vertex_degree`` filtration has been propagated to pyflagser.
- A bug in the C++ ``flagser`` bindings causing persistence diagrams and cell counts to be wrong based on the values of ``min_dimension`` and ``max_dimension`` has been fixed.
- Tests were updated accordingly and `conftest.py` has been improved.
- Bugs in the ``pyflagser`` ``flagser`` functions causing incompatibilities with sparse matrix and non-float datatype have been fixed.
- ``CMakeLists`` has been updated to use C++14. This addresses problem when compiling on MacOS.
Backwards-Incompatible Changes
------------------------------
The library has been fully refactored, which means that most changes were backwards-incompatible. In particular:
- All functions have been renamed as they now include an ``unweighted`` and a ``weighted`` version.
- The ``flag_matrix`` argument have been renamed ``adjacency_matrix``.
Please check the documentation for more information.
Thanks to our Contributors
--------------------------
This release contains contributions from many people:
Guillaume Tauzin, Umberto Lupo, and Julian Burella Pérez.
We are also grateful to all who filed issues or helped resolve them, asked and answered questions, and were part of inspiring discussions.