API Reference#

This page lists the public Python API for calfcv.

Estimators#

class calfcv.Calf(grid=(-1, 1), auc_tol=1e-06, order_col=False, verbose=False)[source]#

Bases: ClassifierMixin, TransformerMixin, BaseEstimator

Coarse approximation linear function.

Calf fits a linear model with coefficients w = (w1, …, wp) to maximize the AUC of the targets predicted by the linear function.

Parameters:

gridtuple, list, or int, default=(-1, 1): The search grid for weight candidates.
auc_tolfloat, default=1e-6: Tolerance above max AUC for inclusion of a feature index.
order_colbool, default=False: Whether to order the columns by individual AUC prior to fitting.
verbosebool, default=False: If True, print status messages.

Attributes:

coef_list of float: Estimated coefficients for the linear fit problem. Only one target should be passed, and this is a 1D list of length n_features.
auc_list of float: The cumulative AUC up to each selected feature.
weights_list of float: The non-zero weights assigned to the selected features.
feature_index_list of int: The indices of the features that contribute positive AUC.
classes_ndarray of shape (n_classes,): The unique class labels.
X_{ndarray, sparse matrix}: The training input features.
y_ndarray: The target vector.
fit_time_float: The number of seconds to fit X to y.

Notes

The feature matrix must be centered at 0. This can be accomplished with sklearn.preprocessing.StandardScaler, or similar. No intercept is calculated.

Examples

>>> import numpy as np
>>> from calfcv import Calf
>>> from sklearn.datasets import make_classification as mc
>>> X, y = mc(n_features=2, n_redundant=0, n_informative=2, n_clusters_per_class=1, random_state=42)
>>> np.round(X[0:3, :], 2)
array([[ 1.23, -0.76],
       [ 0.7 , -1.38],
       [ 2.55,  2.5 ]])
>>> y[0:3]
array([0, 0, 1])
>>> cls = Calf().fit(X, y)
>>> cls.score(X, y)
0.76

decision_function(X)[source]#

Identify confidence scores for the samples.

Parameters:

X{array-like, sparse matrix} of shape (n_samples, n_features): The input features and samples to evaluate.

Returns:

scoresndarray of shape (n_samples,): The decision vector scaled between -1 and 1.

fit(X, y)[source]#

Fit the model according to the given training data.

Parameters:

X{array-like, sparse matrix} of shape (n_samples, n_features): Training vector, where n_samples is the number of samples and n_features is the number of features.
yarray-like of shape (n_samples,): Binary target vector relative to X.

Returns:

selfobject: Fitted estimator.

fit_transform(X, y)[source]#

Fit to the data, then reduce X to the features that contribute positive AUC.

Parameters:

X{array-like, sparse matrix} of shape (n_samples, n_features): The training input features and samples.
yarray-like of shape (n_samples,): Target vector relative to X.

Returns:

X_r{ndarray, sparse matrix} of shape (n_samples, n_selected_features): The input samples with only the selected features.

get_metadata_routing()#

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:

routingMetadataRequest: A MetadataRequest encapsulating routing information.

get_params(deep=True)#

Get parameters for this estimator.

Parameters:

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

Returns:

paramsdict: Parameter names mapped to their values.

predict(X)[source]#

Predict class labels for samples in X.

Parameters:

X{array-like, sparse matrix} of shape (n_samples, n_features): The data matrix for which we want to get the predictions.

Returns:

y_predndarray of shape (n_samples,): Vector containing the predicted class labels for each sample.

predict_proba(X)[source]#

Probability estimates for samples in X.

Parameters:

X{array-like, sparse matrix} of shape (n_samples, n_features): Vector to be scored, where n_samples is the number of samples and n_features is the number of features.

Returns:

class_probndarray of shape (n_samples, n_classes): Returns the probability of the sample for each class in the model, where classes are ordered as they are in self.classes_. To create the probabilities, Calf uses the expit (sigmoid) function.

score(X, y, sample_weight=None)#

Return accuracy on provided data and labels.

In multi-label classification, this is the subset accuracy which is a harsh metric since you require for each sample that each label set be correctly predicted.

Parameters:

Xarray-like of shape (n_samples, n_features): Test samples.
yarray-like of shape (n_samples,) or (n_samples, n_outputs): True labels for X.
sample_weightarray-like of shape (n_samples,), default=None: Sample weights.

Returns:

scorefloat: Mean accuracy of self.predict(X) w.r.t. y.

set_output(*, transform=None)#

Set output container.

Refer to the user guide for more details and Introducing the set_output API for an example on how to use the API.

Parameters:

transform{“default”, “pandas”, “polars”}, default=None

Configure output of transform and fit_transform.

“default”: Default output format of a transformer
“pandas”: DataFrame output
“polars”: Polars output
None: Transform configuration is unchanged

Added in version 1.4: “polars” option was added.

Returns:

selfestimator instance: Estimator instance.

set_params(**params)#

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:

**paramsdict: Estimator parameters.

Returns:

selfestimator instance: Estimator instance.

set_score_request(*, sample_weight: bool | None | str = '$UNCHANGED$') → Calf#

Configure whether metadata should be requested to be passed to the score 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 score 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 score.
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:

sample_weightstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED: Metadata routing for sample_weight parameter in score.

Returns:

selfobject: The updated object.

transform(X)[source]#

Reduce X to the features that contribute positive AUC.

Parameters:

X{array-like, sparse matrix} of shape (n_samples, n_features): The input features and samples.

Returns:

X_r{ndarray, sparse matrix} of shape (n_samples, n_selected_features): The input samples with only the selected features.

class calfcv.CalfCV(grid=(-1, 1), auc_tol=1e-06, order_col=False, cv=None, n_jobs=None, verbose=False)[source]#

Bases: ClassifierMixin, TransformerMixin, BaseEstimator

Coarse approximation linear function with cross validation.

CalfCV fits a linear model with coefficients w = (w1, …, wp) to maximize the AUC of the targets predicted by the linear function. It optimizes weight selection and feature inclusion thresholds through an internal GridSearchCV pipeline.

Parameters:

gridtuple, list of tuples, or int, default=(-1, 1): The candidate search grid(s) for weight candidates to optimize over. Pass a list of tuples (e.g., [(-1, 1), (-1, 0, 1)]) to evaluate multiple grids.
auc_tolfloat or list of floats, default=1e-6: Tolerance above max AUC for inclusion of a feature index. Pass a list to evaluate multiple tolerances.
order_colbool or list of bools, default=False: Whether to order the columns by individual AUC prior to fitting. Pass a list to evaluate both options.
cvint, cross-validation generator or iterable, default=None: Determines the cross-validation splitting strategy for GridSearchCV.
n_jobsint, default=None: Number of jobs to run in parallel for GridSearchCV. -1 means using all processors.
verbosebool, default=False: If True, print status messages.

Attributes:

best_params_dict: Parameter setting that gave the best results on the hold out data.
best_coef_list of float: Estimated coefficients for the linear fit problem from the best model. Only one target should be passed, and this is a 1D list of length n_features.
best_score_float: The best AUC score over the cross validation.
best_auc_list of float: The cumulative AUC up to each selected feature from the best model.
classes_ndarray of shape (n_classes,): The unique class labels.
X_{ndarray, sparse matrix}: The training input features.
y_ndarray: The target vector.
model_GridSearchCV: The fitted grid search pipeline.
fit_time_float: The number of seconds to fit X to y.

Notes

The feature matrix must be centered at 0. If X is dense, a StandardScaler is automatically prepended to the GridSearchCV pipeline.

Examples

>>> import numpy as np
>>> from calfcv import CalfCV
>>> from sklearn.datasets import make_classification as mc
>>> X, y = mc(n_features=2, n_redundant=0, n_informative=2, n_clusters_per_class=1, random_state=42)
>>> np.round(X[0:3, :], 2)
array([[ 1.23, -0.76],
       [ 0.7 , -1.38],
       [ 2.55,  2.5 ]])
>>> y[0:3]
array([0, 0, 1])
>>> cls = CalfCV().fit(X, y)
>>> cls.score(X, y)
0.7

decision_function(X)[source]#

Identify confidence scores for the samples.

Parameters:

X{array-like, sparse matrix} of shape (n_samples, n_features): The input features and samples to evaluate.

Returns:

scoresndarray of shape (n_samples,): The decision vector generated by the best pipeline estimator.

fit(X, y)[source]#

Fit the model according to the given training data and optimize hyperparameters.

Parameters:

X{array-like, sparse matrix} of shape (n_samples, n_features): Training vector, where n_samples is the number of samples and n_features is the number of features.
yarray-like of shape (n_samples,): Binary target vector relative to X.

Returns:

selfobject: Fitted estimator.

fit_transform(X, y)[source]#

Fit to the data, then reduce X to the features that contribute positive AUC.

Parameters:

X{array-like, sparse matrix} of shape (n_samples, n_features): The training input features and samples.
yarray-like of shape (n_samples,): Target vector relative to X.

Returns:

X_r{ndarray, sparse matrix} of shape (n_samples, n_selected_features): The input samples with only the selected features.

get_metadata_routing()#

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:

routingMetadataRequest: A MetadataRequest encapsulating routing information.

get_params(deep=True)#

Get parameters for this estimator.

Parameters:

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

Returns:

paramsdict: Parameter names mapped to their values.

predict(X)[source]#

Predict class labels for samples in X.

Parameters:

X{array-like, sparse matrix} of shape (n_samples, n_features): The data matrix for which we want to get the predictions.

Returns:

y_predndarray of shape (n_samples,): Vector containing the predicted class labels for each sample.

predict_proba(X)[source]#

Probability estimates for samples in X.

Parameters:

X{array-like, sparse matrix} of shape (n_samples, n_features): Vector to be scored, where n_samples is the number of samples and n_features is the number of features.

Returns:

class_probndarray of shape (n_samples, n_classes): Returns the probability of the sample for each class in the model.

score(X, y, sample_weight=None)#

Return accuracy on provided data and labels.

In multi-label classification, this is the subset accuracy which is a harsh metric since you require for each sample that each label set be correctly predicted.

Parameters:

Xarray-like of shape (n_samples, n_features): Test samples.
yarray-like of shape (n_samples,) or (n_samples, n_outputs): True labels for X.
sample_weightarray-like of shape (n_samples,), default=None: Sample weights.

Returns:

scorefloat: Mean accuracy of self.predict(X) w.r.t. y.

set_output(*, transform=None)#

Set output container.

Refer to the user guide for more details and Introducing the set_output API for an example on how to use the API.

Parameters:

transform{“default”, “pandas”, “polars”}, default=None

Configure output of transform and fit_transform.

“default”: Default output format of a transformer
“pandas”: DataFrame output
“polars”: Polars output
None: Transform configuration is unchanged

Added in version 1.4: “polars” option was added.

Returns:

selfestimator instance: Estimator instance.

set_params(**params)#

Set the parameters of this estimator.

Parameters:

**paramsdict: Estimator parameters.

Returns:

selfestimator instance: Estimator instance.

set_score_request(*, sample_weight: bool | None | str = '$UNCHANGED$') → CalfCV#

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

The options for each parameter are:

True: metadata is requested, and passed to score 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 score.
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:

sample_weightstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED: Metadata routing for sample_weight parameter in score.

Returns:

selfobject: The updated object.

transform(X)[source]#

Reduce X to the features that contribute positive AUC.

Parameters:

X{array-like, sparse matrix} of shape (n_samples, n_features): The input features and samples.

Returns:

X_r{ndarray, sparse matrix} of shape (n_samples, n_selected_features): The input samples with only the selected features.