[DOC] Section 1 of user guide/definition of concepts #408

man-shu · 2025-09-15T10:53:34Z

For section 1 of the user guide, which contains the definition of all basic concepts.

codecov · 2025-09-15T11:01:55Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.37%. Comparing base (324d31c) to head (c78aff9).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #408   +/-   ##
=======================================
  Coverage   98.37%   98.37%           
=======================================
  Files          23       23           
  Lines        1602     1602           
=======================================
  Hits         1576     1576           
  Misses         26       26

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

bthirion

I think it could be useful to have in this section a typology of all VI methods.

docs/src/concepts.rst

man-shu

Looks good overall.

Just wondering whether we should introduce the Total Sobol Index in the "Types of VI methods" section or some other place. The original issue #306 mentions it...

man-shu · 2025-09-16T14:47:42Z

docs/src/concepts.rst

+There are two main types of VI methods implemented in HiDimStat:
+
+1. Marginal methods: these methods provide importance to all the features 
+that are related to the output, even if it is caused by spurius correlation. They 


Suggested change

that are related to the output, even if it is caused by spurius correlation. They

that are related to the output, even if it is caused by spurious correlation. They

man-shu · 2025-09-16T14:53:48Z

docs/src/concepts.rst

+1. Marginal methods: these methods provide importance to all the features 
+that are related to the output, even if it is caused by spurius correlation. They 
+are related with testing if :math:`X^j\perp\!\!\!\!\perp Y`.
+Example of such methods is LOCI.


I think it would be useful to provide a reference for LOCI, or at least expand the abbreviation.

Yes, I would also suggest the reference but I think they are not yet available.

For LOCI, I find this reference: Ewald, Fiona Katharina, Ludwig Bothmann, Marvin N. Wright, Bernd Bischl, Giuseppe Casalicchio, and Gunnar König. "A guide to feature importance methods for scientific inference." In World Conference on Explainable Artificial Intelligence, pp. 440-464. Cham: Springer Nature Switzerland, 2024.

What I meant it was the reference to the implemented class, not a bibliography reference.

I think the biblio ref should be good enough for now

The reference for the implementation should be only in the docstring of the class. In this case, we can keep a more general bibliography.

man-shu · 2025-09-16T14:55:30Z

docs/src/concepts.rst

+1. Marginal methods: these methods provide importance to all the features 
+that are related to the output, even if it is caused by spurius correlation. They 
+are related with testing if :math:`X^j\perp\!\!\!\!\perp Y`.
+Example of such methods is LOCI.


Suggested change

Example of such methods is LOCI.

An example of such a method is LOCI.

man-shu · 2025-09-16T15:02:25Z

docs/src/concepts.rst

+i.e., they contribute unique knowledge. They are related with Conditional 
+Independence Testing, which consist in testing if 
+:math:`X^j\perp\!\!\!\!\perp Y\mid X^{-j}`. Examples of such methods are
+:class:`hidimstat.LOCO` and :class:`hidimstat.CFI`.


Suggested change

i.e., they contribute unique knowledge. They are related with Conditional

Independence Testing, which consist in testing if

:math:`X^j\perp\!\!\!\!\perp Y\mid X^{-j}`. Examples of such methods are

:class:`hidimstat.LOCO` and :class:`hidimstat.CFI`.

i.e., they contribute unique knowledge. They are related to Conditional

Independence Testing, which consists of testing whether

:math:`X^j\perp\!\!\!\!\perp Y\mid X^{-j}`. Examples of such methods are

:class:`hidimstat.LOCO` and :class:`hidimstat.CFI`.

man-shu · 2025-09-16T15:08:37Z

docs/src/concepts.rst

+soon).
+
+Variable Selection
+-------------------------------


Suggested change

-------------------------------

------------------

man-shu · 2025-09-16T15:09:06Z

docs/src/concepts.rst

+
+
+High-dimension and correlation
+-----------------------------------


Suggested change

-----------------------------------

------------------------------

man-shu · 2025-09-16T15:14:32Z

docs/src/concepts.rst

+that are related to the output, even if it is caused by spurius correlation. They 
+are related with testing if :math:`X^j\perp\!\!\!\!\perp Y`.


Suggested change

that are related to the output, even if it is caused by spurius correlation. They

are related with testing if :math:`X^j\perp\!\!\!\!\perp Y`.

that are related to the output, even if it is caused by spurius correlation. They

consist of testing whether :math:`X^j\perp\!\!\!\!\perp Y`.

Maybe that sounds better?

It is because they do not directly test whether X is independent of Y because they are variable importance measures, not just for selection. That is why I would say that implicitly they are related to this testing, but they do not consist on this testing.

Ok makes sense!

man-shu · 2025-09-16T15:15:05Z

docs/src/concepts.rst

+statistical control to the discoveries made. Simply selecting the most important 
+features without such control is not valid. Different forms of guarantees can 
+be employed, such as controlling the type-I error or the False Discovery Rate. 
+This step is directly related to the task of Variable Selection.


I might be very wrong, but isn't this section somewhat redundant to the Variable Selection section? Could it be incorporated with the Variable Selection section?

Yes, but I am not sure how. Indeed it is important to make explicit that the power of the library is to provide statistical guarantees too.

Simply add a cross-link ?

We will add sections to describe variable importance concepts (TSI) and variable selection concepts (FWER, FDR, etc.) in the Definition of concepts of the API, see #549

lionelkusch · 2025-09-17T09:13:54Z

docs/src/concepts.rst

+It allow us to rank the variables from more to less important.                            
+
+Here, ``VI`` can be a variable importance method implemented in HiDimStat,
+such as :class:`hidimstat.LOCO` (other methods will support the same API 


If you can use the full name of the model before to introduce the acronym of it, it will be better.

…d selection

…_section1

…stat into userguide_section1

docs/src/concepts.rst

jpaillard · 2025-12-08T10:27:57Z

docs/src/concepts.rst

+
+There are two main types of VI methods implemented in HiDimStat:
+
+1. Marginal methods: these methods provide importance to all the features 


Suggested change

1. Marginal methods: these methods provide importance to all the features

1. **Marginal methods**: these methods provide importance to all the features

jpaillard · 2025-12-08T10:28:08Z

docs/src/concepts.rst

+An example of such methods is Leave One Covariate In (LOCI, 
+:footcite:p:`ewald_2024`).
+
+2. Conditional methods: these methods assign importance only to features that


Suggested change

2. Conditional methods: these methods assign importance only to features that

2. **Conditional methods**: these methods assign importance only to features that

bthirion

I have minor comments. LGTM overall.

bthirion · 2025-12-08T11:06:32Z

docs/src/concepts.rst

+-------------------
+
+Global Variable Importance (VI) aims to assign a measure of
+relevance to each feature :math:`X^j` with respect to a target  :math:`Y` in the


Suggested change

relevance to each feature :math:`X^j` with respect to a target :math:`Y` in the

relevance to each feature :math:`X^j` with respect to a target :math:`y` in the

We will explain that in #546

bthirion · 2025-12-08T11:08:59Z

docs/src/concepts.rst

+statistical control to the discoveries made. Simply selecting the most important 
+features without such control is not valid. Different forms of guarantees can 
+be employed, such as controlling the type-I error or the False Discovery Rate. 
+This step is directly related to the task of Variable Selection.


Simply add a cross-link ?

* init definition of concepts * point to specific VI classes * only d0crt works rn * section on types of variable imp methods * minor * definition * Statistical Inference and concept description * Add explicit information about the gap between variable importance and selection * add ewald bibliography * Typo Knockoff * Notation and small corrections on selection * y as sklearn * Variable selection title --------- Co-authored-by: angelReyero <angelreyerolobo@gmail.com> Co-authored-by: lionel kusch <lionel.a.kusch@inria.fr> Co-authored-by: jpaillard <joseph.paillard@inria.fr>

* add a changelog file * add file for contributors * add changelogtemplate * a what is new for listing the change * update pyproject * add a swithcer of version * include lastest modification * fix a bug * documenation on how to make a release * move build packages Need to be check f this script is still usefull * move file * add contributors * update version * Fix codespell * remove build from isort * fix docstring * update version number * update license declaration * Fix readme file * fix readme for release * update how to make release * rename version * Update release * avoid test\n[skip tests] * fix documentation [skip tests] * update release info * fix management of lastest version * Update pyproject.toml Co-authored-by: bthirion <bertrand.thirion@inria.fr> * Update tools/release/How_to_release.md Co-authored-by: bthirion <bertrand.thirion@inria.fr> * Update tools/release/How_to_release.md Co-authored-by: bthirion <bertrand.thirion@inria.fr> * Update tools/release/How_to_release.md Co-authored-by: bthirion <bertrand.thirion@inria.fr> * Update tools/release/How_to_release.md Co-authored-by: bthirion <bertrand.thirion@inria.fr> * fix * Update tools/release/How_to_release.md Co-authored-by: bthirion <bertrand.thirion@inria.fr> * [skip tests] * fix documentation * update realse notes * fix name of branches for release * Update CHANGELOG.rst Co-authored-by: Joseph Paillard <joseph.paillard@inria.fr> * Update CHANGELOG.rst Co-authored-by: Joseph Paillard <joseph.paillard@inria.fr> * Update CHANGELOG.rst Co-authored-by: Joseph Paillard <joseph.paillard@inria.fr> * update contributor file * [DOC] Section 1 of user guide/definition of concepts (#408) * init definition of concepts * point to specific VI classes * only d0crt works rn * section on types of variable imp methods * minor * definition * Statistical Inference and concept description * Add explicit information about the gap between variable importance and selection * add ewald bibliography * Typo Knockoff * Notation and small corrections on selection * y as sklearn * Variable selection title --------- Co-authored-by: angelReyero <angelreyerolobo@gmail.com> Co-authored-by: lionel kusch <lionel.a.kusch@inria.fr> Co-authored-by: jpaillard <joseph.paillard@inria.fr> * release 0.3.0 --------- Co-authored-by: Joseph Paillard <joseph.paillard@inria.fr> Co-authored-by: bthirion <bertrand.thirion@inria.fr> Co-authored-by: Himanshu Aggarwal <himanshuaggarwal1997@gmail.com> Co-authored-by: angelReyero <angelreyerolobo@gmail.com>

init definition of concepts

b2a620d

man-shu marked this pull request as draft September 15, 2025 10:53

man-shu assigned man-shu and AngelReyero Sep 15, 2025

man-shu added 3 commits September 15, 2025 14:27

point to specific VI classes

240d499

only d0crt works rn

9a71090

section on types of variable imp methods

0eb1d1d

man-shu changed the title ~~Section 1 of user guide/definition of concepts~~ [DOC] Section 1 of user guide/definition of concepts Sep 15, 2025

man-shu and others added 2 commits September 15, 2025 14:54

minor

84aadca

definition

c5f4c3a

bthirion reviewed Sep 15, 2025

View reviewed changes

docs/src/concepts.rst Outdated Show resolved Hide resolved

docs/src/concepts.rst Outdated Show resolved Hide resolved

docs/src/concepts.rst Outdated Show resolved Hide resolved

bthirion reviewed Sep 15, 2025

View reviewed changes

docs/src/concepts.rst Show resolved Hide resolved

Statistical Inference and concept description

e0bb238

man-shu commented Sep 16, 2025

View reviewed changes

lionelkusch reviewed Sep 17, 2025

View reviewed changes

AngelReyero and others added 6 commits September 17, 2025 12:21

Add explicit information about the gap between variable importance an…

2b9e618

…d selection

Merge branch 'main' into userguide_section1

f5b8afb

add ewald bibliography

7e6004a

Merge branch 'main' of github.com:mind-inria/hidimstat into userguide…

0d392a6

…_section1

Merge branch 'userguide_section1' of https://github.com/man-shu/hidim…

a068f52

…stat into userguide_section1

Typo Knockoff

f191587

jpaillard marked this pull request as ready for review December 8, 2025 10:18

jpaillard reviewed Dec 8, 2025

View reviewed changes

AngelReyero added 2 commits December 8, 2025 12:00

Notation and small corrections on selection

a635b27

y as sklearn

63053c2

jpaillard approved these changes Dec 8, 2025

View reviewed changes

bthirion reviewed Dec 8, 2025

View reviewed changes

AngelReyero and others added 2 commits December 8, 2025 15:15

Variable selection title

c78aff9

Merge branch 'main' into userguide_section1

24b073a

jpaillard merged commit 1882f60 into mind-inria:main Dec 8, 2025
6 of 7 checks passed

	that are related to the output, even if it is caused by spurius correlation. They
	that are related to the output, even if it is caused by spurious correlation. They

	Example of such methods is LOCI.
	An example of such a method is LOCI.



		High-dimension and correlation
		-----------------------------------

	-----------------------------------
	------------------------------

		that are related to the output, even if it is caused by spurius correlation. They
		are related with testing if :math:`X^j\perp\!\!\!\!\perp Y`.


		There are two main types of VI methods implemented in HiDimStat:

		1. Marginal methods: these methods provide importance to all the features

	1. Marginal methods: these methods provide importance to all the features
	1. Marginal methods: these methods provide importance to all the features

	2. Conditional methods: these methods assign importance only to features that
	2. Conditional methods: these methods assign importance only to features that

	relevance to each feature :math:`X^j` with respect to a target :math:`Y` in the
	relevance to each feature :math:`X^j` with respect to a target :math:`y` in the

[DOC] Section 1 of user guide/definition of concepts #408

[DOC] Section 1 of user guide/definition of concepts #408

Uh oh!

Conversation

man-shu commented Sep 15, 2025

Uh oh!

codecov bot commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

bthirion left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

man-shu left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bthirion left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

codecov bot commented Sep 15, 2025 •

edited

Loading