geovalidate.ClusterStratifiedKFold¶

class geovalidate.ClusterStratifiedKFold(clusterer, n_splits=5, noise='stratify', noise_label=-1, random_state=None)[source]¶

Cluster-stratified k-fold cross-validator.

Fits a user-supplied clustering estimator (e.g. sklearn.cluster.HDBSCAN, sklearn.cluster.OPTICS, sklearn.cluster.KMeans) to the input locations, then partitions each cluster’s members into n_splits equally sized parts. Every test fold is a stratified sample drawn from every cluster – so each fold spans all clusters rather than holding out a single region.

This is the spatial analogue of StratifiedKFold where the strata are spatial clusters discovered at fit time.

Parameters:¶

clusterer : sklearn-compatible clustering estimator¶

Anything with a fit(coords) method that sets labels_ after fitting. HDBSCAN and OPTICS are the intended targets; KMeans also works. If the estimator already has a labels_ attribute (i.e. was fitted ahead of time) it is used as-is; otherwise it is cloned and refit on the input coordinates. The fitted estimator is stored as clusterer_.

n_splits : int, default 5¶

Number of folds. Each cluster’s members are split into this many parts; clusters smaller than n_splits contribute to only the first len(cluster) folds.

noise : {'stratify', 'drop', 'train_only', 'nearest'}, default 'stratify'¶

How to handle noise points (those whose label equals noise_label).

’stratify’ : distribute noise across folds like a normal cluster.
’drop’ : exclude noise points from both train and test.
’train_only’: noise points appear in every train set, never test.
’nearest’ : each noise point is reassigned to the cluster of its nearest non-noise point and then participates in that cluster’s fold-assignment pool as a regular member.

noise_label : int, default -1¶

Cluster label used by density-based clusterers (HDBSCAN, OPTICS) to mark noise points.

random_state : int, RandomState instance, or None¶

Controls within-cluster shuffling before splitting.

clusterer_[source]¶

The cloned (or passed-in) clusterer after fitting.

Type:¶: fitted clustering estimator

labels_[source]¶

Cluster labels assigned by clusterer_.

Type:¶: ndarray of int, shape (n,)

n_clusters_[source]¶

Number of distinct cluster labels (including noise if present).

Type:¶: int

Examples

>>> from sklearn.cluster import HDBSCAN
>>> ckf = ClusterStratifiedKFold(HDBSCAN(min_cluster_size=5), n_splits=5, random_state=0)
>>> for train_idx, test_idx in ckf.split(gdf):
...     model.fit(X[train_idx], y[train_idx])
...     score = model.score(X[test_idx], y[test_idx])

__init__(clusterer, n_splits=5, noise='stratify', noise_label=-1, random_state=None)[source]¶

Methods

`__init__`(clusterer[, n_splits, noise, ...])
`get_metadata_routing`()	Get metadata routing of this object.
`get_n_splits`([X, y, groups])
`get_params`([deep])	Get parameters for this estimator.
`set_params`(**params)	Set the parameters of this estimator.
`set_split_request`(*[, groups])	Configure whether metadata should be requested to be passed to the `split` method.
`split`(X[, y, groups])	Yield `(train_indices, test_indices)` for each cluster-stratified fold.

get_metadata_routing()[source]¶

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:¶: routing – A MetadataRequest encapsulating routing information.
Return type:¶: MetadataRequest

get_n_splits(X=None, y=None, groups=None)[source]¶

get_params(deep=True)[source]¶

Get parameters for this estimator.

Parameters:¶

deep : bool, default=True¶: If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:¶

params – Parameter names mapped to their values.

Return type:¶

dict

set_params(**params)[source]¶

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:¶

**params : dict¶: Estimator parameters.

Returns:¶

self – Estimator instance.

Return type:¶

estimator instance

set_split_request(*, groups='$UNCHANGED$')[source]¶

Configure whether metadata should be requested to be passed to the split method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

True: metadata is requested, and passed to split if provided. The request is ignored if metadata is not provided.
False: metadata is not requested and the meta-estimator will not pass it to split.
None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:¶

groups : str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED¶: Metadata routing for groups parameter in split.

Returns:¶

self – The updated object.

Return type:¶

object

split(X, y=None, groups=None)[source]¶

Yield (train_indices, test_indices) for each cluster-stratified fold.

Parameters:¶

X : GeoDataFrame | GeoSeries | (n, 2) ndarray¶: Locations to cluster.
y : ignored, present for sklearn API compatibility.¶
groups : ignored, present for sklearn API compatibility.¶

Yields:¶

train (ndarray of int)
test (ndarray of int)