"""Construct and handle Mapper pipelines."""
# License: GNU AGPLv3
from sklearn.pipeline import Pipeline
from .cluster import ParallelClustering
from .nerve import Nerve
from .utils._list_feature_union import ListFeatureUnion
from .utils.pipeline import transformer_from_callable_on_rows, identity
global_pipeline_params = ("memory", "verbose")
nodes_params = ("scaler", "filter_func", "cover")
clust_prepr_params = ("clustering_preprocessing",)
clust_params = ("clusterer", "n_jobs",
"parallel_backend_prefer")
nerve_params = ("min_intersection", "store_edge_elements", "contract_nodes")
clust_prepr_params_prefix = "pullback_cover__"
nodes_params_prefix = "pullback_cover__map_and_cover__"
clust_params_prefix = "clustering__"
nerve_params_prefix = "nerve__"
[docs]class MapperPipeline(Pipeline):
"""Subclass of :class:`sklearn.pipeline.Pipeline` to deal with
pipelines generated by :func:`~gtda.mapper.pipeline.make_mapper_pipeline`.
The :meth:`set_params` method is modified from the corresponding method in
:class:`sklearn.pipeline.Pipeline` to allow for simple access to the
parameters involved in the definition of the Mapper algorithm, without the
need to interface with the nested structure of the Pipeline objects
generated by :func:`~gtda.mapper.pipeline.make_mapper_pipeline`. The
convenience method :meth:`get_mapper_params` shows which parameters can
be set. See the Examples below.
Examples
--------
>>> from sklearn.cluster import DBSCAN
>>> from sklearn.decomposition import PCA
>>> from gtda.mapper import make_mapper_pipeline, CubicalCover
>>> filter_func = PCA(n_components=2)
>>> cover = CubicalCover()
>>> clusterer = DBSCAN()
>>> pipe = make_mapper_pipeline(filter_func=filter_func,
... cover=cover,
... clusterer=clusterer)
>>> print(pipe.get_mapper_params()["clusterer__eps"])
0.5
>>> pipe.set_params(clusterer___eps=0.1)
>>> print(pipe.get_mapper_params()["clusterer__eps"])
0.1
See also
--------
make_mapper_pipeline
"""
# TODO: Abstract away common logic into a more generalisable implementation
[docs] def get_mapper_params(self, deep=True):
"""Get all Mapper parameters for this estimator.
Parameters
----------
deep : boolean, optional, default: ``True``
If ``True``, will return the parameters for this estimator and
contained subobjects that are estimators.
Returns
-------
params : mapping of string to any
Parameter names mapped to their values.
"""
pipeline_params = super().get_params(deep=deep)
return {**{param: pipeline_params[param]
for param in global_pipeline_params},
**self._clean_dict_keys(pipeline_params, nodes_params_prefix),
**self._clean_dict_keys(
pipeline_params, clust_prepr_params_prefix),
**self._clean_dict_keys(pipeline_params, clust_params_prefix),
**self._clean_dict_keys(pipeline_params, nerve_params_prefix)}
[docs] def set_params(self, **kwargs):
"""Set the Mapper parameters.
Valid parameter keys can be listed with :meth:`get_mapper_params()`.
Returns
-------
self
"""
mapper_nodes_kwargs = self._subset_kwargs(kwargs, nodes_params)
mapper_clust_prepr_kwargs = \
self._subset_kwargs(kwargs, clust_prepr_params)
mapper_clust_kwargs = self._subset_kwargs(kwargs, clust_params)
mapper_nerve_kwargs = self._subset_kwargs(kwargs, nerve_params)
if mapper_nodes_kwargs:
super().set_params(
**{nodes_params_prefix + key: mapper_nodes_kwargs[key]
for key in mapper_nodes_kwargs})
[kwargs.pop(key) for key in mapper_nodes_kwargs]
if mapper_clust_prepr_kwargs:
super().set_params(
**{clust_prepr_params_prefix + key:
mapper_clust_prepr_kwargs[key] for key in
mapper_clust_prepr_kwargs})
[kwargs.pop(key) for key in mapper_clust_prepr_kwargs]
if mapper_clust_kwargs:
super().set_params(
**{clust_params_prefix + key: mapper_clust_kwargs[key]
for key in mapper_clust_kwargs})
[kwargs.pop(key) for key in mapper_clust_kwargs]
if mapper_nerve_kwargs:
super().set_params(
**{nerve_params_prefix + key: mapper_nerve_kwargs[key]
for key in mapper_nerve_kwargs})
[kwargs.pop(key) for key in mapper_nerve_kwargs]
super().set_params(**kwargs)
return self
@staticmethod
def _subset_kwargs(kwargs, param_strings):
return {key: value for key, value in kwargs.items()
if key.startswith(param_strings)}
@staticmethod
def _clean_dict_keys(kwargs, prefix):
return {
key[len(prefix):]: kwargs[key]
for key in kwargs
if (key.startswith(prefix)
and not key.startswith(prefix + "steps")
and not key.startswith(prefix + "memory")
and not key.startswith(prefix + "verbose")
and not key.startswith(prefix + "transformer_list")
and not key.startswith(prefix + "n_jobs")
and not key.startswith(prefix + "transformer_weights")
and not key.startswith(prefix + "map_and_cover"))
}
[docs]def make_mapper_pipeline(scaler=None,
filter_func=None,
cover=None,
clustering_preprocessing=None,
clusterer=None,
n_jobs=None,
parallel_backend_prefer=None,
graph_step=True,
min_intersection=1,
store_edge_elements=False,
contract_nodes=False,
memory=None,
verbose=False):
"""Construct a MapperPipeline object according to the specified Mapper
steps [1]_.
The role of this function's main parameters is illustrated in `this diagram
<../../../../_images/mapper_pipeline.svg>`_. All computational steps may
be scikit-learn estimators, including Pipeline objects.
Parameters
----------
scaler : object or None, optional, default: ``None``
If ``None``, no scaling is performed. Otherwise, it must be an
object with a ``fit_transform`` method.
filter_func : object, callable or None, optional, default: ``None``
If ``None``, PCA (:class:`sklearn.decomposition.PCA`) with 2
components and default parameters is used as a default filter
function. Otherwise, it may be an object with a ``fit_transform``
method, or a callable acting on one-dimensional arrays -- in which
case the callable is applied independently to each row of the
(scaled) data.
cover : object or None, optional, default: ``None``
Covering transformer, e.g. an instance of
:class:`~gtda.mapper.OneDimensionalCover` or of
:class:`~gtda.mapper.CubicalCover`. ``None`` is equivalent to passing
an instance of :class:`~gtda.mapper.CubicalCover` with its default
parameters.
clustering_preprocessing : object or None, optional, default: ``None``
If not ``None``, it is a transformer which is applied to the
data independently to the `scaler` -> `filter_func` -> `cover`
pipeline. Clustering is then performed on portions (determined by
the `scaler` -> `filter_func` -> `cover` pipeline) of the transformed
data.
clusterer : object or None, optional, default: ``None``
Clustering object with a ``fit`` method which stores cluster labels.
``None`` is equivalent to passing an instance of
:class:`sklearn.cluster.DBSCAN` with its default parameters.
n_jobs : int or None, optional, default: ``None``
The number of jobs to use in a joblib-parallel application of the
clustering step across pullback cover sets. To be used in
conjunction with `parallel_backend_prefer`. ``None`` means 1 unless
in a :obj:`joblib.parallel_backend` context. ``-1`` means using all
processors.
parallel_backend_prefer : ``"processes"`` | ``"threads"`` | ``None``, \
optional, default: ``None``
Soft hint for the default joblib backend to use in a joblib-parallel
application of the clustering step across pullback cover sets. To be
used in conjunction with `n_jobs`. The default process-based backend is
"loky" and the default thread-based backend is "threading". See [2]_.
graph_step : bool, optional, default: ``True``
Whether the resulting pipeline should stop at the calculation of the
(refined) Mapper cover, or include the construction of the Mapper
graph.
min_intersection : int, optional, default: ``1``
Minimum size of the intersection between clusters required for creating
an edge in the Mapper graph. Ignored if `graph_step` is set to
``False``.
store_edge_elements : bool, optional, default: ``False``
Whether the indices of data elements associated to Mapper edges (i.e.
in the intersections allowed by `min_intersection`) should be stored in
the :class:`igraph.Graph` object output by the pipeline's
:meth:`fit_transform`. When ``True``, might lead to large
:class:`igraph.Graph` objects.
contract_nodes : bool, optional, default: ``False``
If ``True``, any node representing a cluster which is a strict subset
of the cluster corresponding to another node is eliminated, and only
one maximal node is kept.
memory : None, str or object with the joblib.Memory interface, \
optional, default: ``None``
Used to cache the fitted transformers which make up the pipeline. This
is advantageous when the fitting of early steps is time consuming and
only later steps in the pipeline are modified (e.g. using
:meth:`set_params`) before refitting on the same data. To be used
exactly as for :func:`sklearn.pipeline.make_pipeline`. By default, no
no caching is performed. If a string is given, it is the path to the
caching directory. See [3]_.
verbose : bool, optional, default: ``False``
If True, the time elapsed while fitting each step will be printed as it
is completed.
Returns
-------
mapper_pipeline : :class:`~gtda.mapper.pipeline.MapperPipeline` object
Output Mapper pipeline. The output of `mapper_pipeline`'s
:meth:`fit_transform` is: a) an :class:`igraph.Graph` object as per the
output of :class:`~gtda.mapper.nerve.Nerve`, when `graph_step` is
``True``; b) a list of lists of tuples as per the output of
:class:`~gtda.mapper.ParallelClustering` (or input of
:class:`~gtda.mapper.Nerve`), otherwise.
Examples
--------
Basic usage with default parameters
>>> import numpy as np
>>> from gtda.mapper import make_mapper_pipeline
>>> mapper = make_mapper_pipeline()
>>> print(mapper.__class__)
<class 'gtda.mapper.pipeline.MapperPipeline'>
>>> mapper_params = mapper.get_mapper_params()
>>> print(mapper_params["filter_func"].__class__)
<class 'sklearn.decomposition._pca.PCA'>
>>> print(mapper_params["cover"].__class__)
<class 'gtda.mapper.cover.CubicalCover'>
>>> print(mapper_params["clusterer"].__class__)
<class 'sklearn.cluster._dbscan.DBSCAN'>
>>> X = np.random.random((10000, 4)) # 10000 points in 4-dimensional space
>>> mapper_graph = mapper.fit_transform(X) # Create the mapper graph
>>> print(type(mapper_graph))
igraph.Graph
>>> # Node metadata stored as vertex attributes in graph object
>>> print(mapper_graph.vs.attributes())
['pullback_set_label', 'partial_cluster_label', 'node_elements']
>>> # Find which points belong to first node of graph
>>> node_id = 0
>>> node_elements = mapper_graph.vs["node_elements"]
>>> print(f"Node ID: {node_id}, Node elements: {node_elements[node_id]}, "
... f"Data points: {X[node_elements[node_id]")
Node Id: 0,
Node elements: [8768],
Data points: [[0.01838998 0.76928754 0.98199244 0.0074299 ]]
Using a scaler from scikit-learn, a filter function from
``gtda.mapper.filter``, and a clusterer from ``gtda.mapper.cluster``
>>> from sklearn.preprocessing import MinMaxScaler
>>> from gtda.mapper import Projection, FirstHistogramGap
>>> scaler = MinMaxScaler()
>>> filter_func = Projection(columns=[0, 1])
>>> clusterer = FirstHistogramGap()
>>> mapper = make_mapper_pipeline(scaler=scaler,
... filter_func=filter_func,
... clusterer=clusterer)
Using a callable acting on each row of X separately
>>> import numpy as np
>>> from gtda.mapper import OneDimensionalCover
>>> cover = OneDimensionalCover()
>>> mapper.set_params(scaler=None, filter_func=np.sum, cover=cover)
Setting the memory parameter to cache each step and avoid recomputation
of early steps
>>> from tempfile import mkdtemp
>>> from shutil import rmtree
>>> cachedir = mkdtemp()
>>> mapper.set_params(memory=cachedir, verbose=True)
>>> mapper_graph = mapper.fit_transform(X)
[Pipeline] ............ (step 1 of 3) Processing scaler, total= 0.0s
[Pipeline] ....... (step 2 of 3) Processing filter_func, total= 0.0s
[Pipeline] ............. (step 3 of 3) Processing cover, total= 0.0s
[Pipeline] .... (step 1 of 3) Processing pullback_cover, total= 0.0s
[Pipeline] ........ (step 2 of 3) Processing clustering, total= 0.3s
[Pipeline] ............. (step 3 of 3) Processing nerve, total= 0.0s
>>> mapper.set_params(min_intersection=3)
>>> mapper_graph = mapper.fit_transform(X)
[Pipeline] ............. (step 3 of 3) Processing nerve, total= 0.0s
>>> # Clear the cache directory when you don't need it anymore
>>> rmtree(cachedir)
Using a large dataset for which parallelism in clustering across
the pullback cover sets can be beneficial
>>> from sklearn.cluster import DBSCAN
>>> mapper = make_mapper_pipeline(clusterer=DBSCAN(),
... n_jobs=6,
... memory=mkdtemp(),
... verbose=True)
>>> X = np.random.random((100000, 4))
>>> mapper.fit_transform(X)
[Pipeline] ............ (step 1 of 3) Processing scaler, total= 0.0s
[Pipeline] ....... (step 2 of 3) Processing filter_func, total= 0.1s
[Pipeline] ............. (step 3 of 3) Processing cover, total= 0.6s
[Pipeline] .... (step 1 of 3) Processing pullback_cover, total= 0.7s
[Pipeline] ........ (step 2 of 3) Processing clustering, total= 1.9s
[Pipeline] ............. (step 3 of 3) Processing nerve, total= 0.3s
>>> mapper.set_params(n_jobs=1)
>>> mapper.fit_transform(X)
[Pipeline] ........ (step 2 of 3) Processing clustering, total= 5.3s
[Pipeline] ............. (step 3 of 3) Processing nerve, total= 0.3s
See also
--------
MapperPipeline, method_to_transform
References
----------
.. [1] G. Singh, F. Mémoli, and G. Carlsson, "Topological methods for the
analysis of high dimensional data sets and 3D object recognition";
in *SPBG*, pp. 91--100, 2007.
.. [2] "Thread-based parallelism vs process-based parallelism", in
`joblib documentation
<https://joblib.readthedocs.io/en/latest/parallel.html>`_.
.. [3] "Caching transformers: avoid repeated computation", in
`scikit-learn documentation \
<https://scikit-learn.org/stable/modules/compose.html>`_.
"""
# TODO: Implement parameter validation
if scaler is None:
_scaler = identity(validate=False)
else:
_scaler = scaler
# If filter_func is not a scikit-learn transformer, hope it as a
# callable to be applied on each row separately. Then attempt to create a
# FunctionTransformer object to implement this behaviour.
if filter_func is None:
from sklearn.decomposition import PCA
_filter_func = PCA(n_components=2)
elif not hasattr(filter_func, "fit_transform"):
_filter_func = transformer_from_callable_on_rows(filter_func)
else:
_filter_func = filter_func
if cover is None:
from .cover import CubicalCover
_cover = CubicalCover()
else:
_cover = cover
if clustering_preprocessing is None:
_clustering_preprocessing = identity(validate=True)
else:
_clustering_preprocessing = clustering_preprocessing
if clusterer is None:
from sklearn.cluster import DBSCAN
_clusterer = DBSCAN()
else:
_clusterer = clusterer
map_and_cover = Pipeline(
steps=[("scaler", _scaler),
("filter_func", _filter_func),
("cover", _cover)],
verbose=verbose)
all_steps = [
("pullback_cover", ListFeatureUnion(
[("clustering_preprocessing", _clustering_preprocessing),
("map_and_cover", map_and_cover)])),
("clustering", ParallelClustering(
_clusterer,
n_jobs=n_jobs,
parallel_backend_prefer=parallel_backend_prefer))
]
if graph_step:
all_steps.append(
("nerve", Nerve(min_intersection=min_intersection,
store_edge_elements=store_edge_elements,
contract_nodes=contract_nodes))
)
mapper_pipeline = MapperPipeline(
steps=all_steps, memory=memory, verbose=verbose)
return mapper_pipeline