zen_mapper
==========

.. py:module:: zen_mapper


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/zen_mapper/adapters/index
   /autoapi/zen_mapper/cover/index
   /autoapi/zen_mapper/mapper/index
   /autoapi/zen_mapper/types/index


Classes
-------

.. autoapisummary::

   zen_mapper.Width_Balanced_Cover


Functions
---------

.. autoapisummary::

   zen_mapper.sk_learn
   zen_mapper.to_networkx
   zen_mapper.precomputed_cover
   zen_mapper.rectangular_cover
   zen_mapper.mapper


Package Contents
----------------

.. py:function:: sk_learn(base_clusterer: C) -> zen_mapper.types.Clusterer[C]

   Wraps a scikit-learn clusterer for use with zen-mapper.

   This function acts as an adapter, allowing scikit-learn's clustering
   algorithms to be integrated into the zen-mapper pipeline. Note: any
   datapoints which are considered noise by the base clusterer are ignored.

   :param base_clusterer: An instance of a scikit-learn compatible clustering algorithm.
                          This object should have a `fit_predict` method and a `labels_`
                          attribute after fitting, which is standard for scikit-learn
                          clusterers.
   :type base_clusterer: C

   :returns: An object conforming to the zen-mapper `Clusterer` protocol, which
             wraps the provided `clusterer`. This allows zen-mapper to use the
             scikit-learn clusterer's `fit_predict` methods within its pipeline. A
             copy of the fitted base clusterer is also returned as metadata allowing
             for inspection of the fitted model (e.g., centroids, parameters,
             dendrograms) after the mapper pipeline.
   :rtype: Clusterer[C]


.. py:function:: to_networkx(komplex: zen_mapper.types.Komplex)

   Converts a zen-mapper komplex to a networkx graph

   This function takes a `Komplex` object, which represents a simplicial complex,
   and converts it into a `networkx.Graph` object. The vertices of the `Komplex`
   become the nodes in the `networkx` graph, and the 1-simplices (edges) of
   the `Komplex` become the edges in the `networkx` graph.

   :param komplex: The `Komplex` object to convert. This object is expected to
                   have a `vertices` attribute and support indexing for its
                   simplices (e.g., `komplex[1]` for 1-simplices).
   :type komplex: Komplex

   :returns: A `networkx.Graph` object representing the 0- and 1-dimensional
             structure of the input `Komplex`.
   :rtype: networkx.Graph

   :raises ImportError: If the `networkx` library is not installed.


.. py:class:: Width_Balanced_Cover(n_elements: numpy.typing.ArrayLike, percent_overlap: float)

   A cover comprised of equally sized rectangular elements

   :param n_elements: the number of covering elements along each dimension. If the data is
                      dimension d this results in d^n covering elements.
   :type n_elements: ArrayLike
   :param percent_overlap: a number between 0 and 1 representing the ammount of overlap between
                           adjacent covering elements.
   :type percent_overlap: float

   :raises Value Error: if n_elements < 1
   :raises Value Error: if percent_overlap is not in (0,1)


   .. py:attribute:: n_elements


   .. py:attribute:: percent_overlap


   .. py:method:: __call__(data)


.. py:function:: precomputed_cover(cover: zen_mapper.types.Cover) -> zen_mapper.types.CoverScheme

   A precomputed cover

   :param cover: the precomputed cover to use
   :type cover: Cover


.. py:function:: rectangular_cover(centers, widths, data, tol=1e-09)

.. py:function:: mapper(data: numpy.ndarray, projection: numpy.ndarray, cover_scheme: zen_mapper.types.CoverScheme, clusterer: zen_mapper.types.Clusterer[M], dim: int | None, min_intersection: int = 1) -> zen_mapper.types.MapperResult[M]

   Constructs a simplicial complex representation of the data.

   :param data:
   :type data: np.ndarray
   :param projection: The output of the lens/filter function on the data. Must have the same
                      number of elements as data.
   :type projection: np.ndarray
   :param cover_scheme: For cover generation. Should be a callable object that takes a
                        numpy array and returns a list of list(indices).
   :type cover_scheme: CoverScheme
   :param clusterer: A callable object that takes in a dataset and returns an iterator of
                     numpy arrays which contain indices for clustered points.
   :type clusterer: Clusterer
   :param dim: The highest dimension of the mapper complex to compute.
   :type dim: int
   :param min_intersection: The minimum intersection required between clusters to make a simplex.
   :type min_intersection: int

   :returns: An object containing:
             - nodes: List of clusters where each cluster is a list of data indices.
             - nerve: A complete list of simplices.
             - cover: List of list(indices) corresponding to elements of the cover.
   :rtype: MapperResult