zen_mapper¶
Submodules¶
Classes¶
A cover of 1D data with roughly equal data points per interval. |
|
A cover comprised of equally sized rectangular elements |
|
Output of a Mapper computation |
Functions¶
|
Wraps a scikit-learn clusterer for use with zen-mapper. |
|
Converts a zen-mapper komplex to a networkx graph |
|
A precomputed cover |
|
|
|
Constructs a simplicial complex representation of the data. |
Package Contents¶
- zen_mapper.sk_learn(base_clusterer: C, precomputed: bool | None = None) zen_mapper.types.Clusterer[numpy.ndarray, 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.
- Parameters:
base_clusterer (C) – 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.
precomputed (bool, optional) – True if the scikit-learn algorithm is expecting a distance matrix. If not specified the adapter attempts to detect this from base_clusterer.
- 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.
- Return type:
Clusterer[C]
- zen_mapper.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.
- Parameters:
komplex (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).
- Returns:
A networkx.Graph object representing the 0- and 1-dimensional structure of the input Komplex.
- Return type:
networkx.Graph
- Raises:
ImportError – If the networkx library is not installed.
- class zen_mapper.Data_Balanced_Cover(n_elements: int, percent_overlap: float)¶
A cover of 1D data with roughly equal data points per interval.
The cover is constructed by partitioning the sorted indices \([0, \dots, N-1]\) into intervals of approximately equal size, then mapping those index-regions back to the original data positions.
Each bin has a base size and step calculated as:
\[base\_size = \frac{N}{k - (k - 1) \times \text{overlap}} \]\[step = base\_size \times (1 - \text{overlap}) \]where \(k\) is n_elements.
- Parameters:
- Raises:
ValueError – If n_elements < 1 or percent_overlap is not in the range (0, 1).
Notes
A percent_overlap of 0.5 means each interval shares approximately 50% of its points with the subsequent interval.
- _cover¶
- n_elements¶
- percent_overlap¶
- __call__(data: numpy.typing.ArrayLike)¶
Partition the input data into overlapping intervals containing approximately equal numbers of points.
This method sorts the input data and applies a width-balanced cover to the indices. It then maps these index-based regions back to the original data indices to create the balanced cover.
- Parameters:
data (array_like) – A 1-dimensional array of data points to be partitioned.
- Returns:
A list containing the indices of the original data points belonging to each cover element. Each element in the list is an np.ndarray.
- Return type:
list of ndarray
- Raises:
ValueError – If the input data is not 1-dimensional.
ValueError – If the number of points in data is less than the requested n_elements.
- class zen_mapper.Width_Balanced_Cover(n_elements: numpy.typing.ArrayLike, percent_overlap: float)¶
A cover comprised of equally sized rectangular elements
- Parameters:
n_elements (ArrayLike) – the number of covering elements along each dimension. If the data is dimension d this results in d^n covering elements.
percent_overlap (float) – a number between 0 and 1 representing the ammount of overlap between adjacent covering elements.
- Raises:
Value Error – if n_elements < 1
Value Error – if percent_overlap is not in (0,1)
- n_elements¶
- percent_overlap¶
- __call__(data)¶
- zen_mapper.precomputed_cover(cover: zen_mapper.types.Cover) zen_mapper.types.CoverScheme¶
A precomputed cover
- Parameters:
cover (Cover) – the precomputed cover to use
- zen_mapper.rectangular_cover(centers, widths, data, tol=1e-09)¶
- zen_mapper.mapper(data: H, projection: numpy.ndarray, cover_scheme: zen_mapper.types.CoverScheme, clusterer: zen_mapper.types.Clusterer[H, M], dim: int | None, min_intersection: int = 1) zen_mapper.types.MapperResult[M]¶
Constructs a simplicial complex representation of the data.
- Parameters:
data (np.ndarray)
projection (np.ndarray) – The output of the lens/filter function on the data. Must have the same number of elements as data.
cover_scheme (CoverScheme) – For cover generation. Should be a callable object that takes a numpy array and returns a list of list(indices).
clusterer (Clusterer) – A callable object that takes in a dataset and returns an iterator of numpy arrays which contain indices for clustered points.
dim (int) – The highest dimension of the mapper complex to compute.
min_intersection (int) – The minimum intersection required between clusters to make a simplex.
- 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.
- Return type:
- class zen_mapper.MapperResult¶
Bases:
Generic[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.
- 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]
- 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:
- 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.
- cluster_metadata¶
A list of clustering metadata objects. The object cluster_metadata[i] corresponds to whatever metadata the clusterer produced on cover element i. If cover element i was empty this will cluster_metadata[i] is None.
- Type:
list[M | None]
- nodes: list[numpy.ndarray]¶
