Skip to content

[DOC] Fixed shape inconsistencies in docstring for importance and selection arrays. #711

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
GrituX wants to merge 1 commit into
base: main
Choose a base branch
from
Open

[DOC] Fixed shape inconsistencies in docstring for importance and selection arrays. #711

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 6 additions & 20 deletions src/hidimstat/base_perturbation.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -179,34 +179,20 @@ def importance(self, X, y):
The input samples to compute importance scores for.
y : array-like of shape (n_samples,)

importances_ : ndarray of shape (n_groups,)
The importance scores for each group of covariates.
A higher score indicates greater importance of that group.

Returns
-------
importances_ : ndarray of shape (n_features,)
Importance scores for each feature.

Attributes
----------
loss_reference_ : float
The loss of the model with the original (non-perturbed) data.
loss_ : dict
Dictionary with indices as keys and arrays of perturbed losses as values.
Contains the loss values for each permutation of each group.
importances_ : ndarray of shape (n_groups,)
The calculated importance scores for each group.
pvalues_ : ndarray of shape (n_groups,)
P-values from one-sample t-test testing if importance scores are
significantly greater than 0.
The importance scores for each feature group.
A higher score indicates greater importance of that group.

@bthirion bthirion Jul 10, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A higher score indicates greater importance of that group.
A larger score indicates greater importance of that group.


Notes
-----
The importance score for each group is calculated as the mean increase in loss
when that group is perturbed, compared to the reference loss.
A higher importance score indicates that perturbing that group leads to
worse model performance, suggesting those features are more important.
When no group has been specified, the importance is computed for each single
feature.
"""
self._check_fit()
self._check_compatibility(X)
Expand Down Expand Up @@ -347,7 +333,7 @@ class BasePerturbationCV(BaseVariableImportance):
----------
importance_estimators_ : list of BasePerturbation instances
List of BasePerturbation instances for each fold.
importances_ : ndarray of shape (n_groups, n_splits)
importances_ : ndarray of shape (n_groups, n_folds)
Importance scores for each fold and each group of covariates.
pvalues_ : ndarray of shape (n_groups,)
P-values for importance scores computed across folds.
Expand Down Expand Up @@ -502,7 +488,7 @@ def importance(self, X, y):

Returns
-------
importances_ : ndarray of shape (n_features, n_groups)
importances_ : ndarray of shape (n_groups, n_folds)
The importance scores for each group of features.
"""
statistical_test = check_statistical_test(
Expand Down
6 changes: 3 additions & 3 deletions src/hidimstat/base_variable_importance.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -295,7 +295,7 @@ def fdr_selection(

Returns
-------
selected : ndarray of int
selected : ndarray of int of shape (n_features,)
Integer array indicating the selected features.
1 indicates selected features with positive effects,
-1 indicates selected features with negative effects,
Expand Down Expand Up @@ -361,7 +361,7 @@ def fwer_selection(

Returns
-------
selected : ndarray of int
selected : ndarray of int of shape (n_features,)
Integer array indicating the selected features.
1 indicates selected features with positive effects,
-1 indicates selected features with negative effects,
Expand Down Expand Up @@ -446,7 +446,7 @@ def plot_importance(
]
elif isinstance(feature_names, list):
assert np.all(isinstance(name, str) for name in feature_names), (
"The feature_names should be a list of the string"
"feature_names should be a list of strings"
)
else:
raise ValueError("feature_names should be a list")
Expand Down
10 changes: 5 additions & 5 deletions src/hidimstat/conditional_feature_importance.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -298,11 +298,11 @@ def cfi_importance(
"""
Returns
-------
selection : ndarray of shape (n_features,)
Boolean array indicating selected features (True = selected)
importances : ndarray of shape (n_features,)
Feature importance scores/test statistics.
pvalues : ndarray of shape (n_features,)
selection : ndarray of shape (n_groups,)
Boolean array indicating selected feature groups (True = selected)
importances : ndarray of shape (n_groups,)
Feature group importance scores/test statistics.
pvalues : ndarray of shape (n_groups,)
P-values for importance scores.
""",
)
Expand Down
25 changes: 17 additions & 8 deletions src/hidimstat/desparsified_lasso.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,12 +90,12 @@ class DesparsifiedLasso(BaseVariableImportance):

Attributes
----------
importances_ : ndarray of shape (n_features)
Debiased coefficient estimates.
pvalues_ : ndarray of shape (n_features)
Two-sided p-values.
pvalues_corr_ : ndarray of shape (n_features)
Multiple testing corrected p-values.
importances_ : ndarray of shape (n_features,)
Debiased coefficient estimates for each feature.
pvalues_ : ndarray of shape (n_features,)
Two-sided p-values for each feature.
pvalues_corr_ : ndarray of shape (n_features,)
Multiple testing corrected p-values for each feature.
sigma_hat_ : float or ndarray of shape (n_task, n_task)
Estimated noise level.
precision_diagonal_ : ndarray of shape (n_features)
Expand Down Expand Up @@ -317,7 +317,8 @@ def __sklearn_is_fitted__(self):
)

def _initial_fit(self, estimator, X_, y_):
"""Run initial fit of a sklearn estimator.
"""
Run initial fit of a sklearn estimator.

Use during fit if an unfitted estimator was passed at instantiation.
"""
Expand Down Expand Up @@ -365,7 +366,7 @@ def importance(self, X=None, y=None):
Returns
-------
importances_ : ndarray of shape (n_features,) or (n_features, n_task)
Desparsified lasso coefficient estimates.
Desparsified lasso coefficient estimates for each feature.

Notes
-----
Expand Down Expand Up @@ -472,6 +473,14 @@ def fdr_selection(
):
"""
Overrides the signature to set two_tailed_test=True by default.

Returns
-------
selected : ndarray of int of shape (n_features,)
Integer array indicating the selected features.
1 indicates selected features with positive effects,
-1 indicates selected features with negative effects,
0 indicates non-selected features.
"""
return super().fdr_selection(
fdr=fdr,
Expand Down
16 changes: 13 additions & 3 deletions src/hidimstat/ensemble_clustered_inference.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,11 @@ def importance(self, X=None, y=None):
Not used, present for API consistency by convention.
y :
Not used, present for API consistency by convention.

Returns
-------
importances_ : ndarray, shape (n_clusters,) or (n_clusters, n_tasks)
Estimated coefficients at cluster level.
"""
del y
del X
Expand Down Expand Up @@ -156,8 +161,8 @@ def fit_importance(self, X, y):

Returns
-------
self : CluDL
Fitted estimator with computed importances.
importances_ : ndarray, shape (n_clusters,) or (n_clusters, n_tasks)
Estimated coefficients at cluster level.
"""
self.fit(X, y)
self.importance(X, y)
Expand Down Expand Up @@ -415,6 +420,11 @@ def importance(self, X=None, y=None):
Not used, present for API consistency by convention.
y :
Not used, present for API consistency by convention.

Returns
-------
importances_ : ndarray, shape (n_features,) or (n_features, n_tasks)
Estimated coefficients at the feature level.
"""
del y
del X
Expand Down Expand Up @@ -460,7 +470,7 @@ def fit_importance(self, X, y):
Returns
-------
importances_ : ndarray, shape (n_features,) or (n_features, n_tasks)
Estimated coefficients at feature level.
Estimated coefficients at the feature level.
"""
self.fit(X, y)
self.importance(X, y)
Expand Down
24 changes: 11 additions & 13 deletions src/hidimstat/knockoffs.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ class ModelXKnockoff(BaseVariableImportance):
Attributes
----------
importances_ : ndarray, shape (n_repeats, n_features)
Test statistics for each repeat.
Knockoff statistics :math:`W_j` for each original feature across repetitions.
pvalues_ : ndarray, shape (n_repeats, n_features)
Empirical p-values for each repeat.
threshold_fdr_ : float
Expand Down Expand Up @@ -225,9 +225,8 @@ def importance(self, X=None, y=None):

Returns
-------
importances_ : ndarray of shape (n_features,)
Feature importance scores for each feature.
Higher absolute values indicate higher importance.
importances_ : ndarray of shape (n_repeats, n_features)
Knockoff statistics :math:`W_j` for each original feature across repetitions.

Notes
-----
Expand Down Expand Up @@ -269,9 +268,8 @@ def fit_importance(self, X, y):

Returns
-------
importances_ : ndarray of shape (n_features,)
Feature importance scores (p-values) for each feature.
Lower values indicate higher importance. Values range from 0 to 1.
importances_ : ndarray of shape (n_repeats, n_features)
Knockoff statistics :math:`W_j` for each original feature across repetitions.

Notes
-----
Expand Down Expand Up @@ -325,7 +323,7 @@ def fdr_selection(

Returns
-------
numpy.ndarray
selected: numpy.ndarray of shape (n_features,)
Boolean array indicating selected features (True for selected, False for not selected)

Raises
Expand Down Expand Up @@ -449,7 +447,7 @@ def lasso_coefficient_difference_statistic(estimators, n_features):
Returns
-------
test_statistic : ndarray, shape (n_repeats, n_features)
Knockoff statistics :math:`W_j` for each original feature across repeats. The number
Knockoff statistics :math:`W_j` for each original feature across repetitions. The number
of repeats corresponds to the length of the estimators list.
"""
test_statistic_list = []
Expand Down Expand Up @@ -515,12 +513,12 @@ def _empirical_knockoff_pval(test_score):

Parameters
----------
test_score : 1D ndarray, shape (n_features, )
test_score : 1D ndarray, shape (n_features,)
Vector of test statistics.

Returns
-------
pvals : 1D ndarray, shape (n_features, )
pvals : 1D ndarray, shape (n_features,)
Vector of empirical p-values.
"""
pvals = []
Expand All @@ -547,15 +545,15 @@ def _empirical_knockoff_eval(test_score, ko_threshold):

Parameters
----------
test_score : 1D ndarray, shape (n_features, )
test_score : 1D ndarray, shape (n_features,)
Vector of test statistics.

ko_threshold : float
Threshold level.

Returns
-------
evals : 1D ndarray, shape (n_features, )
evals : 1D ndarray, shape (n_features,)
Vector of empirical e-values.
"""
evals = []
Expand Down
10 changes: 5 additions & 5 deletions src/hidimstat/leave_one_covariate_in.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -280,11 +280,11 @@ def loci_importance(
"""
Returns
-------
selection : ndarray of shape (n_features,)
Boolean array indicating selected features (True = selected)
importances : ndarray of shape (n_features,)
Feature importance scores/test statistics.
pvalues : ndarray of shape (n_features,)
selection : ndarray of shape (n_groups,)
Boolean array indicating selected feature groups (True = selected).
importances : ndarray of shape (n_groups,)
Feature group importance scores/test statistics.
pvalues : ndarray of shape (n_groups,)
P-values computed for the marginal importance.
""",
)
Expand Down
19 changes: 8 additions & 11 deletions src/hidimstat/leave_one_covariate_out.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,15 +115,12 @@ def importance(self, X, y):
The input samples to compute importance scores for.
y : array-like of shape (n_samples,)

Returns
-------
importances_ : ndarray of shape (n_groups,)
The importance scores for each group of covariates.
A higher score indicates greater importance of that group.

Returns
-------
importances_ : ndarray of shape (n_features,)
Importance scores for each feature.

Attributes
----------
loss_reference_ : float
Expand Down Expand Up @@ -275,12 +272,12 @@ def loco_importance(
"""
Returns
-------
selection : ndarray of shape (n_features,)
Boolean array indicating selected features (True = selected)
importances : ndarray of shape (n_features,)
Feature importance scores/test statistics.
pvalues : ndarray of shape (n_features,)
None because there is no p-value for this method
selection : ndarray of shape (n_groups,)
Boolean array indicating selected feature groups (True = selected).
importances : ndarray of shape (n_groups,)
Feature group importance scores/test statistics.
pvalues : ndarray of shape (n_groups,)
None because there is no p-value for this method.
""",
)

Expand Down
10 changes: 5 additions & 5 deletions src/hidimstat/permutation_feature_importance.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,11 +130,11 @@ def pfi_importance(
"""
Returns
-------
selection : ndarray of shape (n_features,)
Boolean array indicating selected features (True = selected)
importances : ndarray of shape (n_features,)
Feature importance scores/test statistics.
pvalues : ndarray of shape (n_features,)
selection : ndarray of shape (n_groups,)
Boolean array indicating selected feature groups (True = selected)
importances : ndarray of shape (n_groups,)
Feature group importance scores/test statistics.
pvalues : ndarray of shape (n_groups,)
P-values for importance scores.
""",
)
Expand Down
Loading