multipers 1.1.3__tar.gz → 1.2.1__tar.gz

{multipers-1.1.3/multipers.egg-info → multipers-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: multipers
-Version: 1.1.3
+Version: 1.2.1
 Summary: Scikit-style Multiparameter persistence toolkit
 Home-page: https://github.com/DavidLapous/multipers
 Author: David Loiseaux

{multipers-1.1.3 → multipers-1.2.1}/README.md

@@ -1,11 +1,14 @@
 # Multipers
+[![Downloads](https://static.pepy.tech/badge/multipers)](https://pepy.tech/project/multipers)
+<br>
 Scikit-style multiparameter persistent homology python library. 
 This librairy aims to provide easy to use and performant strategies for applied multiparameter topology.
+A non-exhaustive list of features can be found in the **Features** section.
 <br> Meant to be integrated in [the Gudhi library](https://gudhi.inria.fr/).
 
+
 ## Installation
-### Dependencies
-Using conda
+Some dependencies are needed, e.g., using conda
 ```sh
 conda create -n python311
 conda activate python311
@@ -14,7 +17,6 @@ pip install filtration-domination pykeops
 ```
 Other libraries may be required for some specific functions, e.g., pytorch for to compute the rank invariant.
 
-### Installation
 #### Using pip (Recommended)
 Precompiled versions, for linux and macos, are available [on PyPI](https://pypi.org/project/multipers/). Just use 
 ```sh
@@ -26,47 +28,47 @@ Clone the repo, and in a terminal, in the root folder
 conda install python=3.11 cxx-compiler boost tbb tbb-devel numpy matplotlib gudhi scikit-learn cython sympy tqdm cycler typing shapely -c conda-forge
 pip install .
 ```
-It has been tested with python 3.11 on Linux (gcc12) and Macos (clang14-clang16). 
-If the build fails (on macos) see a fix at the end of the readme. 
-Don't hesitate to fill an issue if this doesn't work out of the box; it can help future users ;-).
+Mostly tested on *latest everything* on linux. **For macos users**, this command may fail, see a fix at the end.
 
 ## How to use
-### Tutorial notebooks
-We provide a few notebooks, which explains, in different scenarios, how to use our library. <br>
-**Take a look at them !** They are in the tutorial folder.<br>
-If something is not clear, or you have trouble using a function, don't hesitate to fill an issue; I'll try to update this.
+To get a first idea on how this library works, we provide a few tutorial notebooks, in the **tutorial** folder.
+<br>
+If something is not clear, or a function not covered, feel free to open an issue to ask for an example (or open a PR with a new notebook).
+<br>
+As the example zoo is far from covering everything, don't hesitate to submit something if you find an interesting example.
 
 
-## References and similar projects
-Filled box refers to implemented or interfaced code.
+## Features, and linked projects
+This librairy features a bunch of different functions and helpers. See below for a non-exhaustive list.
+<br>Filled box refers to implemented or interfaced code.
  - [x] [Multiparameter Module Approximation](https://arxiv.org/abs/2206.02026) provides the multiparameter simplicial structure, aswell as technics of approximating modules, via interval decompostion modules. It is also very useful for visualization.
  - [x] [Stable Vectorization of Multiparameter Persistent Homology using Signed Barcodes as Measures](https://arxiv.org/abs/2306.03801) provides fast representations of multiparameter persistence modules, by using their signed barcodes decompositions, and encoding it into signed measures. Implemented decompositions : Euler surfaces, Hilbert function, rank invariant (i.e. rectangles). It also provides representation technics for Machine Learning, i.e., Sliced Wasserstein kernels, Vectorizations.
  - [x] [A Framework for Fast and Stable Representations of Multiparameter Persistent Homology Decompositions](https://arxiv.org/abs/2306.11170) Provides a vectorization framework for interval decomposable modules, for Machine Learning. Currently implemented as an extension of MMA.
- - [x] [Filtration-Domination in Bifiltered Graphs](https://doi.org/10.1137/1.9781611977561.ch3) Allows for 2-parameter edge collapses for 1-critical clique complexes. **Very useful** to speed up, e.g., Rips-Codensity bifiltrations. 
+ - [x] [Multiparameter Persistence Landscapes](https://jmlr.org/papers/v21/19-054.html) A vectoriazation technic for multiparameter persistence modules.
+ - [x] [Filtration-Domination in Bifiltered Graphs](https://doi.org/10.1137/1.9781611977561.ch3) Allows for 2-parameter edge collapses for 1-critical clique complexes. **Very useful** to speed up, e.g., Rips-Codensity bifiltrations.
+ - [x] [Chunk Reduction for Multi-Parameter Persistent Homology](https://doi.org/10.4230/LIPIcs.SoCG.2019.37) Multi-filtration preprocessing algorithm.
  - [x] [Computing Minimal Presentations and Bigraded Betti Numbers of 2-Parameter Persistent Homology](https://arxiv.org/abs/1902.05708) Minimal presentation of multiparameter persistence modules, using [mpfree](https://bitbucket.org/mkerber/mpfree/src/master/). Hilbert Decomposition Signed Measures, and MMA decompositions can be computed using the mpfree backend.
- - [ ] [Projected distances for multi-parameter persistence modules](https://arxiv.org/abs/2206.08818) Provides a strategy to estimate the convolution distance between multiparameter persistence module using projected barcodes. Implementation is a WIP.
- - [ ] [Delaunay Bifiltrations of Functions on Point Clouds](https://arxiv.org/abs/2310.15902) Provides an alternative to function rips bifiltrations, using Delaunay complexes.
- - [ ] [Efficient Two-Parameter Persistence Computation via Cohomology](https://doi.org/10.4230/LIPIcs.SoCG.2023.15) Minimal presentations for 2-parameter persistence clique complexes.
- - [Rivet](https://github.com/rivetTDA/rivet) Interactive two parameter persistence. From multipers to rivet is implemented, WIP for the rest.
+ - [x] [Delaunay Bifiltrations of Functions on Point Clouds](https://arxiv.org/abs/2310.15902) Provides an alternative to function rips bifiltrations, using Delaunay complexes. Very good alternative to Rips-Density like bi-filtrations.
+ - [x] [Rivet](https://github.com/rivetTDA/rivet) Interactive two parameter persistence
+ - [ ] [Backend only] [Projected distances for multi-parameter persistence modules](https://arxiv.org/abs/2206.08818) Provides a strategy to estimate the convolution distance between multiparameter persistence module using projected barcodes. Implementation is a WIP.
+ - [ ] [Partial, and experimental] [Efficient Two-Parameter Persistence Computation via Cohomology](https://doi.org/10.4230/LIPIcs.SoCG.2023.15) Minimal presentations for 2-parameter persistence algorithm.
 
+If I missed something, or you want to add something, feel free to open an issue.
 
 ## Authors
-[David Loiseaux](https://www-sop.inria.fr/members/David.Loiseaux/index.html), 
+[David Loiseaux](https://www-sop.inria.fr/members/David.Loiseaux/index.html),<br>
+[Hannah Schreiber](https://github.com/hschreiber) (Persistence backend code),<br>
 [Luis Scoccola](https://luisscoccola.com/) 
-(Möbius inversion in python, degree-rips using [persistable](https://github.com/LuisScoccola/persistable) and [RIVET](https://github.com/rivetTDA/rivet/)), 
-[Mathieu Carrière](https://www-sop.inria.fr/members/Mathieu.Carriere/) (Sliced Wasserstein).
+(Möbius inversion in python, degree-rips using [persistable](https://github.com/LuisScoccola/persistable) and [RIVET](https://github.com/rivetTDA/rivet/)),<br>
+[Mathieu Carrière](https://www-sop.inria.fr/members/Mathieu.Carriere/) (Sliced Wasserstein)<br>
 
 ## Contributions
-Hannah Schreiber
 
 Feel free to contribute, report a bug on a pipeline, or ask for documentation by opening an issue.<br>
-**Any contribution is welcome**.
-
-
 
 
 ## For mac users 
-Due to the clang compiler, one may have to disable a compilator optimization to compile `multipers`: in the `setup.py` file, add the 
+Due to apple's clang compiler, one may have to disable a compilator optimization to compile `multipers`: in the `setup.py` file, add the 
 ```bash
 -fno-aligned-new
 ```

multipers-1.2.1/multipers/__init__.py

@@ -0,0 +1,12 @@
+# Doc
+import multipers.simplex_tree_multi
+import multipers.multiparameter_module_approximation
+import multipers.slicer
+import multipers.io
+
+
+# Shortcuts
+from multipers.simplex_tree_multi import SimplexTreeMulti
+from multipers._signed_measure_meta import signed_measure
+from multipers._slicer_meta import Slicer
+from multipers.multiparameter_module_approximation import module_approximation

{multipers-1.1.3 → multipers-1.2.1}/multipers/_signed_measure_meta.py

@@ -1,11 +1,21 @@
+from multipers.plots import plot_signed_measures
 from multipers.simplex_tree_multi import SimplexTreeMulti  # Typing hack
-from typing import Optional
+from typing import Optional, Union
 import numpy as np
 from multipers.simplex_tree_multi import _available_strategies
 
+from multipers.slicer import (
+    Slicer,
+    SlicerClement,
+    SlicerVineGraph,
+    SlicerVineSimplicial,
+)
+
 
 def signed_measure(
-    simplextree: SimplexTreeMulti,
+    simplextree: Union[
+        SimplexTreeMulti, Slicer, SlicerClement, SlicerVineGraph, SlicerVineSimplicial
+    ],
     degree: Optional[int] = None,
     degrees=[None],
     mass_default=None,
@@ -19,19 +29,25 @@ def signed_measure(
     thread_id: str = "",
     mpfree_path: Optional[str] = None,
     grid_conversion: Optional[list] = None,
+    coordinate_measure: bool = False,
     num_collapses: int = 0,
     **infer_grid_kwargs,
 ):
     """
-    Computes the signed measures given by the decomposition of the hilbert function or the euler characteristic.
+    Computes the signed measures given by the decomposition of the hilbert
+    function or the euler characteristic.
 
     Input
     -----
-     - simplextree:SimplexTreeMulti, the multifiltered simplicial complex. Its recommended to squeeze the simplextree first.
-     - mass_default: Either None, or 'auto' or 'inf', or array-like of floats. Where to put the default mass to get a zero-mass measure.
-     - degree:int|None / degrees:list[int] the degrees to compute. None represents the euler characteristic.
+     - simplextree:SimplexTreeMulti, the multifiltered simplicial complex.
+       Its recommended to squeeze the simplextree first.
+     - mass_default: Either None, or 'auto' or 'inf', or array-like of floats.
+       Where to put the default mass to get a zero-mass measure.
+     - degree:int|None / degrees:list[int] the degrees to compute.
+       None represents the euler characteristic.
      - plot:bool, plots the computed measures if true.
-     - n_jobs:int, number of jobs. Defaults to #cpu, but when doing parallel computations of signed measures, we recommend setting this to 1.
+     - n_jobs:int, number of jobs.
+       Defaults to #cpu, but when doing parallel computations of signed measures, we recommend setting this to 1.
      - verbose:bool, prints c++ logs.
 
     Output
@@ -39,6 +55,12 @@ def signed_measure(
     `[signed_measure_of_degree for degree in degrees]`
     with `signed_measure_of_degree` of the form `(dirac location, dirac weights)`.
     """
+    if not isinstance(simplextree, SimplexTreeMulti):
+        return _signed_measure_from_slicer(
+            simplextree,
+            plot=plot,
+            grid_conversion=grid_conversion,
+        )
     assert invariant is None or invariant in [
         "hilbert",
         "rank_invariant",
@@ -59,21 +81,24 @@ def signed_measure(
     if not simplextree._is_squeezed:
         simplextree_ = SimplexTreeMulti(simplextree)
         if grid_conversion is None:
-            simplextree_.grid_squeeze(
+            grid_conversion = simplextree_.get_filtration_grid(
                 grid_strategy=grid_strategy,
-                coordinate_values=not (backend == "mpfree"),
                 **infer_grid_kwargs,
             )  # put a warning ?
-        else:
-            simplextree_.grid_squeeze(
-                grid_conversion,
-                coordinate_values=not (backend == "mpfree"),
-                **infer_grid_kwargs,
-            )
+        simplextree_.grid_squeeze(
+            grid_conversion,
+            coordinate_values=True,
+            **infer_grid_kwargs,
+        )
         if num_collapses != 0:
             simplextree_.collapse_edges(num_collapses)
     else:
         simplextree_ = simplextree
+        if grid_conversion is None:
+            grid_conversion = [np.asarray(f) for f in simplextree_.filtration_grid]
+    if coordinate_measure:
+        grid_conversion = None
+
     if backend == "mpfree":
         if mpfree_path is not None:
             import multipers.io as mio
@@ -87,17 +112,11 @@ def signed_measure(
         from multipers.io import minimal_presentation_from_mpfree
 
         minimal_presentation = minimal_presentation_from_mpfree(
-            simplextree,
+            simplextree_,
             True,
             degrees[0],
             id=thread_id,
         )
-        if grid_conversion is not None:
-            grid_conversion = grid_conversion
-        elif simplextree._is_squeezed:
-            grid_conversion = simplextree.filtration_grid
-        else:
-            grid_conversion = None
         sms = _signed_measure_from_scc(
             minimal_presentation, grid_conversion=grid_conversion
         )
@@ -122,11 +141,13 @@ def signed_measure(
             mass_default.ndim == 1
             and mass_default.shape[0] == simplextree.num_parameters
         )
+    # assert not coordinate_measure or grid_conversion is None
 
     if invariant in ["rank_invariant", "rank"]:
         assert (
             simplextree.num_parameters == 2
         ), "Rank invariant only implemented for 2-parameter modules."
+        assert not coordinate_measure, "Not implemented"
         from multipers.rank_invariant import signed_measure as smri
 
         sms = smri(
@@ -141,6 +162,7 @@ def signed_measure(
             "euler",
             "euler_characteristic",
         ], "Provide a degree to compute hilbert function."
+        # assert not coordinate_measure, "Not implemented"
         from multipers.euler_characteristic import euler_signed_measure
 
         sms = [
@@ -191,3 +213,24 @@ def _signed_measure_from_scc(minimal_presentation, grid_conversion=None):
     else:
         sm = [(pts, weights)]
     return sm
+
+
+def _signed_measure_from_slicer(
+    slicer: Union[Slicer, SlicerClement, SlicerVineGraph, SlicerVineSimplicial],
+    plot: bool = False,
+    grid_conversion=None,
+):
+    pts = slicer.get_filtrations()
+    dims = slicer.get_dimensions()
+    weights = 1 - 2 * ((1 + dims) % 2)
+    if grid_conversion is not None:
+        pts = np.asarray(pts, dtype=int)
+        coords = np.empty(shape=pts.shape, dtype=float)
+        for i in range(coords.shape[1]):
+            coords[:, i] = np.asarray(grid_conversion[i])[pts[:, i]]
+        sm = [(coords, weights)]
+    else:
+        sm = [(pts, weights)]
+    if plot:
+        plot_signed_measures(sm)
+    return sm

multipers-1.2.1/multipers/_slicer_meta.py

@@ -0,0 +1,103 @@
+from typing import Literal, Optional
+
+
+import multipers.slicer as mps
+import multipers.simplex_tree_multi
+from multipers.simplex_tree_multi import SimplexTreeMulti
+import multipers.io as mio
+import numpy as np
+from copy import deepcopy
+
+
+def _blocks2boundary_dimension_grades(
+    blocks, filtration_type=np.float32, num_parameters: int = -1
+):
+    """
+    Turns blocks, aka scc, into the input of non-simplicial slicers.
+    """
+    if num_parameters < 0:
+        for b in blocks:
+            if len(b[0]) > 0:
+                num_parameters = np.asarray(b[0]).shape[1]
+                break
+        if num_parameters < 0:
+            # empty presentation
+            # return [], [], np.empty(0, dtype=filtration_type)
+            raise ValueError("Empty Filtration")
+    rblocks = deepcopy(blocks)
+    rblocks.reverse()
+    block_sizes = [len(b[0]) for b in rblocks]
+    S = np.cumsum([0, 0] + block_sizes)
+    multifiltration = np.concatenate(
+        tuple(
+            b[0] if len(b[0]) > 0 else np.empty((0, num_parameters)) for b in rblocks
+        ),
+        dtype=filtration_type,
+    )
+    boundary = tuple(x + S[i] for i, b in enumerate(rblocks) for x in b[1])
+    dimensions = np.fromiter(
+        (i for i, b in enumerate(rblocks) for _ in range(len(b[0]))), dtype=int
+    )
+    return boundary, dimensions, multifiltration
+
+
+def Slicer(
+    st: SimplexTreeMulti | list | str,
+    backend: Literal["matrix", "clement", "graph"] = "matrix",
+    vineyard: bool = True,
+):
+    """
+    Given a simplextree or blocks (a.k.a scc for python),
+    returns a structure that can compute persistence on line (or more)
+    slices, eventually vineyard update, etc.
+
+    This can be used to compute interval-decomposable module approximations
+    or signed measures, using, e.g.
+     - `multipers.module_approximation(this, *args)`
+     - `multipers.signed_measure(this, *args)`
+
+    Note : it is recommended and sometime required to apply
+        a minimal presentation before computing these functions !
+    `mp.slicer.minimal_presentation(slicer, *args, **kwargs)`
+
+    st : SimplexTreeMulti or scc-like blocks
+    backend: slicer backend;
+    vineyard: vineyard capable (may slow down computations if true)
+    """
+    if isinstance(st, SimplexTreeMulti):
+        if vineyard:
+            if backend == "matrix":
+                return mps.SlicerVineSimplicial(st)
+            if backend == "clement":
+                raise ValueError("This one takes a minpres")
+            if backend == "graph":
+                return mps.SlicerVineGraph(st)
+            raise ValueError(f"Inimplemented backend {backend}.")
+        if backend == "matrix":
+            return mps.SlicerNoVineSimplicial(st)
+        if backend == "clement":
+            raise ValueError("Clement is Vineyard")
+        if backend == "graph":
+            raise ValueError("Graph is Vineyard")
+    if backend == "graph":
+        raise ValueError("Graph is simplicial, incompatible with minpres")
+    if isinstance(st, SimplexTreeMulti):
+        blocks = mio.minimal_presentation_from_mpfree(st)
+    elif isinstance(st, str):
+        blocks = mio.scc_parser(st)
+    else:
+        blocks = st
+
+    boundary, dimensions, multifiltrations = _blocks2boundary_dimension_grades(blocks)
+    if vineyard:
+        if backend == "matrix":
+            return mps.Slicer(boundary, dimensions, multifiltrations)
+
+        if backend == "clement":
+            return mps.SlicerClement(boundary, dimensions, multifiltrations)
+    if backend == "matrix":
+        return mps.SlicerNoVine(boundary, dimensions, multifiltrations)
+    if backend == "clement":
+        raise ValueError("Clement is vineyard")
+
+    raise ValueError(f"Unimplemented combo : f{backend=}, f{vineyard=}")

{multipers-1.1.3 → multipers-1.2.1}/multipers/distances.py

@@ -51,6 +51,8 @@ def sm_distance(sm1, sm2, reg=0, reg_m=0, numItermax=10000, p=1):
         empty_tensor = np.array([])  # uniform weights
     elif isinstance(x, torch.Tensor):
         empty_tensor = torch.tensor([])  # uniform weights
+    else:
+        raise ValueError("Unimplemented backend.")
 
     if reg == 0:
         return ot.lp.emd2(empty_tensor, empty_tensor, M=loss) * len(x)