zen_mapper.types ================ .. py:module:: zen_mapper.types Classes ------- .. autoapisummary:: zen_mapper.types.Cover zen_mapper.types.CoverScheme zen_mapper.types.Simplex zen_mapper.types.Komplex zen_mapper.types.Clusterer zen_mapper.types.MapperResult Module Contents --------------- .. py:class:: Cover Bases: :py:obj:`Protocol` Protocol for a cover A set is represented as a numpy array of indices into the original data set. For instance `[0, 4, 3]` represents the set with the 0th, 4th, and 3rd elements from the original dataset. A cover is a collection of these sets. It is expected that these cover the dataset however no effort is made to enforce this constraint. Specifcially we require that you can iterate over the sets in the cover and that you can report the number of cover elements. In particular this means a list of arrays or a set of arrays will work. It is unlikely that you will actually implement this protocol, what you probably want is :class:`CoverScheme`. .. py:method:: __len__() -> int Returns the number of sets in the cover. :returns: The number of sets in the cover. :rtype: int .. py:method:: __iter__() -> collections.abc.Iterator[numpy.typing.ArrayLike] Returns an iterator over the sets in the cover. Each element yielded by the iterator is expected to be array-like, suitable for conversion to a NumPy array. The elements of these arrays are indices into the original data set :Yields: *npt.ArrayLike* -- An array-like object representing a set in the cover. .. py:class:: CoverScheme Bases: :py:obj:`Protocol` Protocol for a cover scheme A cover scheme is a function or callable object which takes the projected data and produces a `Cover` object. See the example :doc:`/examples/custom_cover` for a more detailed look at how to create a custom covering scheme. .. py:method:: __call__(data: numpy.ndarray) -> Cover Generates a `Cover` from the input data. :param data: The input data :type data: np.ndarray :returns: A `Cover` object representing the generated cover of the data. :rtype: Cover .. py:class:: Simplex Bases: :py:obj:`tuple`\ [\ :py:obj:`int`\ , :py:obj:`Ellipsis`\ ] A thin representation of a simplex A simplex is an ordered collection of vertex ids without repetition. This implementation is essentially a python tuple with some convenience methods bolted on. :param vertices: Vertex ids for the simplex :type vertices: Iterable[int] :raises ValueError: If `vertices` contains repeated elements (a simplex must have unique vertices). :raises ValueError:: If `vertices` is empty (a simplex must have at least one vertex). .. rubric:: Examples >>> s1 = Simplex([1, 0, 2]) >>> s1 (0, 1, 2) >>> s2 = Simplex((5,)) >>> s2 (5,) .. py:property:: dim :type: int The dimension of the simplex The dimension of a simplex is defined to be one less than the number of elements in the simplex. Thus a 0-simplex (a vertex) is comprised of a single point, a 1-simplex (an edge) is comprised of two points, and so on. .. py:property:: faces :type: collections.abc.Iterable[Simplex] All the faces of a simplex A simplex θ is a face of τ if and only if θ ⊆ τ. Note that as τ ⊆ τ that τ is a face of τ! :Yields: *simplex* -- a face of the simplex .. py:property:: vertices :type: collections.abc.Iterable[int] .. py:class:: Komplex(simplices: collections.abc.Iterable[Simplex] | None = None) A basic simplicial complex A `Komplex` is a collection of simplices. It provides methods for adding simplices, checking for their presence, iterating over them, and querying their properties like dimension and vertices. At this time we do not enforce closure propreties for these simplicial complexes. This class is optimized for construction, querying it is slow. If you seek to do much with it we recomend converting it to something else. :param simplices: An initial collection of `Simplex` objects to populate the complex. If `None`, the complex starts empty. :type simplices: Iterable[Simplex], optional .. method:: add(simplex) Adds a single simplex to the complex. .. method:: dim Returns the highest dimension of any simplex in the complex. .. method:: __contains__(simplex) Checks if a given simplex is present in the complex. .. method:: __getitem__(ind) Yields all simplices of a specific dimension. .. method:: __iter__() Iterates over all simplices in the complex. .. method:: vertices Yields all unique vertices (0-simplices) in the complex. .. py:attribute:: _simplices :type: set[Simplex] .. py:method:: add(simplex: Simplex) -> None Adds a simplex to the simplicial complex. :param simplex: The `Simplex` object to add to the complex. :type simplex: Simplex .. py:property:: dim :type: int Returns the dimension of the simplicial complex. The dimension of the complex is the highest dimension of any simplex it contains. An empty complex has a dimension of 0. :returns: The dimension of the complex. :rtype: int .. py:method:: __len__() -> int .. py:method:: __contains__(simplex: Simplex) -> bool Checks if a given simplex is present in the complex. :param simplex: The `Simplex` object to check for existence in the complex. :type simplex: Simplex :returns: `True` if the simplex is in the complex, `False` otherwise. :rtype: bool .. py:method:: __getitem__(ind: int) -> collections.abc.Iterable[Simplex] Yields all simplices of a specific dimension from the complex. :param ind: The dimension of the simplices to retrieve (e.g., 0 for vertices, 1 for edges, 2 for triangles, etc.). :type ind: int :Yields: *Simplex* -- A simplex of the specified dimension. .. py:method:: __iter__() Iterates over all simplices contained within the complex. :Yields: *Simplex* -- Each simplex present in the complex. .. py:property:: vertices :type: collections.abc.Iterable[int] Yields all unique vertex identifiers (0-simplices) present in the complex. :returns: An iterable of integer vertex identifiers. :rtype: Iterable[int] .. py:class:: Clusterer Bases: :py:obj:`Protocol`\ [\ :py:obj:`M`\ ] A callable that partitions a dataset. A clusterer takes a dataset and divides it into distinct groups, known as a partition. A partition is a collection of arrays, where each array contains indices referencing the original dataset. These index arrays must collectively include all data points from the original dataset, and no data point should belong to more than one array (i.e., the arrays are disjoint and cover the entire dataset). For example, for a dataset with 6 elements, `[[1, 2, 3], [0, 4], [5]]` is a valid partition. However, `[[1, 2, 3], [4], [5]]` is not valid because the element at index `0` is missing. Similarly, `[[1, 2, 3], [0, 4], [0, 5]]` is not valid because the element at index `0` appears in multiple arrays. In addition to the partition, the clusterer also produces metadata. The clusterer, when called, must return a tuple containing two elements: the partition (an iterable of NumPy arrays, where each array holds indices) and the associated metadata. If there is no meaningful metadata it should return None. For a more concrete example of how to specify a custom clusterer for use in zen mapper see the example :doc:`/examples/custom_clusterer`. .. py:method:: __call__(data: numpy.ndarray) -> tuple[collections.abc.Iterable[numpy.ndarray], M] .. py:class:: MapperResult Bases: :py:obj:`Generic`\ [\ :py:obj:`M`\ ] Output of a Mapper computation This dataclass encapsulates all the output generated by applying the Mapper algorithm. It includes information about the Mapper complex, the constructed cover, and any metadata associated with the clusters of the complex. .. attribute:: nodes A list of NumPy arrays, where each array represents the points that belong to a specific node in the Mapper graph. Each `np.ndarray` corresponds to a cluster formed by the algorithm. :type: list[np.ndarray] .. attribute:: nerve A `Komplex` object representing the nerve of the cover. This `Komplex` object defines the topological structure of the Mapper graph, where vertices correspond to the `nodes` in this result. :type: Komplex .. attribute:: cover Each inner list contains the indices of the original data points that fall into a specific cover element. This provides a mapping from the original dataset to the cover. :type: list[list[int]] .. attribute:: cluster_metadata A list of metadata objects, where each object corresponds to a cluster (node) in the Mapper graph. The type `M` is generic, allowing for flexible storage of any additional information relevant to each cluster, such as cluster statistics, labels, or other derived properties. :type: list[M] .. py:attribute:: nodes :type: list[numpy.ndarray] .. py:attribute:: nerve :type: Komplex .. py:attribute:: cover :type: list[list[int]] .. py:attribute:: cluster_metadata :type: list[M]