Scikit-learn compatibility¶

All estimators implemented in gwlearn are designed to provide scikit-learn compatible API. However, that is occasionally tricky due to the need of geometry as an additional argument in fit, predict or score. Luckily, there is a way thanks to scikit-learn’s (experimental) support of metadata routing.

import geopandas as gpd
from geodatasets import get_path
from sklearn import set_config
from sklearn.model_selection import GridSearchCV

from gwlearn.linear_model import GWLinearRegression

The metadata routing is not enabled by default, hence if you’d like to use it, you need to enable the configuration.

set_config(enable_metadata_routing=True)

You can then initialise the estimator class and use .set_* methods to indicate that the geometry argument shall be routed alongside X and y.

gwlr = GWLinearRegression(fixed=False, keep_models=True, bandwidth=25)
gwlr.set_fit_request(geometry=True)
gwlr.set_predict_request(geometry=True)
gwlr.set_score_request(geometry=True)

GWLinearRegression(bandwidth=25, keep_models=True)

In a Jupyter environment, please rerun this cell to show the HTML representation or trust the notebook.
On GitHub, the HTML representation is unable to render, please try loading this page with nbviewer.org.

A model prepared like this can be consumed by sklearn’s Pipeline or GridSearchCV.

gdf = gpd.read_file(get_path("geoda.guerry"))

gs = GridSearchCV(gwlr, {'include_focal': [True, False]}, cv=2)
gs.fit(
    gdf[['Crm_prp', 'Litercy', 'Donatns', 'Lottery']],
    gdf["Suicids"],
    geometry=gdf.representative_point()
)

GridSearchCV(cv=2, estimator=GWLinearRegression(bandwidth=25, keep_models=True),
             param_grid={'include_focal': [True, False]})

You can then retrieve the outcome.

gs.best_estimator_.include_focal

True

This way, gwlearn estimators can be included in your workflows with ease.

It is recommended to disable metadata routing once you’re done.

set_config(enable_metadata_routing=False)

	bandwidth	25
	fixed	False
	kernel	'bisquare'
	include_focal	True
	graph	None
	n_jobs	-1
	fit_global_model	True
	strict	False
	keep_models	True
	temp_folder	None
	batch_size	None
	verbose	False

	estimator estimator: estimator object This is assumed to implement the scikit-learn estimator interface. Either estimator needs to provide a ``score`` function, or ``scoring`` must be passed.	GWLinearRegre...p_models=True)
	param_grid param_grid: dict or list of dictionaries Dictionary with parameters names (`str`) as keys and lists of parameter settings to try as values, or a list of such dictionaries, in which case the grids spanned by each dictionary in the list are explored. This enables searching over any sequence of parameter settings.	{'include_focal': [True, False]}
	scoring scoring: str, callable, list, tuple or dict, default=None Strategy to evaluate the performance of the cross-validated model on the test set. If `scoring` represents a single score, one can use: - a single string (see :ref:`scoring_string_names`); - a callable (see :ref:`scoring_callable`) that returns a single value; - `None`, the `estimator`'s :ref:`default evaluation criterion ` is used. If `scoring` represents multiple scores, one can use: - a list or tuple of unique strings; - a callable returning a dictionary where the keys are the metric names and the values are the metric scores; - a dictionary with metric names as keys and callables as values. See :ref:`multimetric_grid_search` for an example.	None
	n_jobs n_jobs: int, default=None Number of jobs to run in parallel. ``None`` means 1 unless in a :obj:`joblib.parallel_backend` context. ``-1`` means using all processors. See :term:`Glossary ` for more details. .. versionchanged:: v0.20 `n_jobs` default changed from 1 to None	None
	refit refit: bool, str, or callable, default=True Refit an estimator using the best found parameters on the whole dataset. For multiple metric evaluation, this needs to be a `str` denoting the scorer that would be used to find the best parameters for refitting the estimator at the end. Where there are considerations other than maximum score in choosing a best estimator, ``refit`` can be set to a function which returns the selected ``best_index_`` given ``cv_results_``. In that case, the ``best_estimator_`` and ``best_params_`` will be set according to the returned ``best_index_`` while the ``best_score_`` attribute will not be available. The refitted estimator is made available at the ``best_estimator_`` attribute and permits using ``predict`` directly on this ``GridSearchCV`` instance. Also for multiple metric evaluation, the attributes ``best_index_``, ``best_score_`` and ``best_params_`` will only be available if ``refit`` is set and all of them will be determined w.r.t this specific scorer. See ``scoring`` parameter to know more about multiple metric evaluation. See :ref:`sphx_glr_auto_examples_model_selection_plot_grid_search_digits.py` to see how to design a custom selection strategy using a callable via `refit`. See :ref:`this example ` for an example of how to use ``refit=callable`` to balance model complexity and cross-validated score. .. versionchanged:: 0.20 Support for callable added.	True
	cv cv: int, cross-validation generator or an iterable, default=None Determines the cross-validation splitting strategy. Possible inputs for cv are: - None, to use the default 5-fold cross validation, - integer, to specify the number of folds in a `(Stratified)KFold`, - :term:`CV splitter`, - An iterable yielding (train, test) splits as arrays of indices. For integer/None inputs, if the estimator is a classifier and ``y`` is either binary or multiclass, :class:`StratifiedKFold` is used. In all other cases, :class:`KFold` is used. These splitters are instantiated with `shuffle=False` so the splits will be the same across calls. Refer :ref:`User Guide ` for the various cross-validation strategies that can be used here. .. versionchanged:: 0.22 ``cv`` default value if None changed from 3-fold to 5-fold.	2
	verbose verbose: int Controls the verbosity: the higher, the more messages. - >1 : the computation time for each fold and parameter candidate is displayed; - >2 : the score is also displayed; - >3 : the fold and candidate parameter indexes are also displayed together with the starting time of the computation.	0
	pre_dispatch pre_dispatch: int, or str, default='2n_jobs' Controls the number of jobs that get dispatched during parallel execution. Reducing this number can be useful to avoid an explosion of memory consumption when more jobs get dispatched than CPUs can process. This parameter can be: - None, in which case all the jobs are immediately created and spawned. Use this for lightweight and fast-running jobs, to avoid delays due to on-demand spawning of the jobs - An int, giving the exact number of total jobs that are spawned - A str, giving an expression as a function of n_jobs, as in '2n_jobs'	'2*n_jobs'
	error_score error_score: 'raise' or numeric, default=np.nan Value to assign to the score if an error occurs in estimator fitting. If set to 'raise', the error is raised. If a numeric value is given, FitFailedWarning is raised. This parameter does not affect the refit step, which will always raise the error.	nan
	return_train_score return_train_score: bool, default=False If ``False``, the ``cv_results_`` attribute will not include training scores. Computing training scores is used to get insights on how different parameter settings impact the overfitting/underfitting trade-off. However computing the scores on the training set can be computationally expensive and is not strictly required to select the parameters that yield the best generalization performance. .. versionadded:: 0.19 .. versionchanged:: 0.21 Default value was changed from ``True`` to ``False``	False

	bandwidth	25
	fixed	False
	kernel	'bisquare'
	include_focal	True
	graph	None
	n_jobs	-1
	fit_global_model	True
	strict	False
	keep_models	True
	temp_folder	None
	batch_size	None
	verbose	False