feat: Extend .frame() API with format and query parameters

[Premkumar-2004]

Extended CoefficientsDisplay.frame() with three new parameters:

format ("long" | "wide" | "auto") - Controls output shape

long (default): Original format, one row per coefficient
wide: Features as rows, labels/splits as columns
auto: Wide for EstimatorReport/CV, long for ComparisonReport
aggregate (bool) - For CV reports, shows mean ± std instead of individual splits

query (dict) - Filter by column values, e.g., {"label": "setosa"}

[github-actions]

Documentation preview @ ccec1da

[github-actions]

Coverage Report for skore/

File	Stmts	Miss	Cover	Missing
skore/src/skore
__init__.py	26	0	100%
_config.py	31	0	100%
_login.py	14	0	100%
exceptions.py	4	4	0%	4, 15, 19, 23
skore/src/skore/_sklearn
__init__.py	6	0	100%
_base.py	73	8	89%	272–279
feature_names.py	26	0	100%
find_ml_task.py	61	0	100%
types.py	28	1	96%	30
skore/src/skore/_sklearn/_comparison
__init__.py	7	0	100%
inspection_accessor.py	27	1	96%	114
metrics_accessor.py	166	2	98%	179, 1138
report.py	111	3	97%	488, 491, 497
utils.py	57	0	100%
skore/src/skore/_sklearn/_cross_validation
__init__.py	9	0	100%
data_accessor.py	40	0	100%
inspection_accessor.py	20	1	95%	113
metrics_accessor.py	169	5	97%	1054, 1115, 1118, 1144–1145
report.py	125	4	96%	492, 502, 505, 511
skore/src/skore/_sklearn/_estimator
__init__.py	9	0	100%
data_accessor.py	61	2	96%	84, 188
inspection_accessor.py	70	2	97%	316, 330
metrics_accessor.py	367	6	98%	427, 431, 446, 476, 1661, 1744
report.py	158	4	97%	443–444, 463, 466
skore/src/skore/_sklearn/_plot
__init__.py	3	0	100%
base.py	57	2	96%	59–60
utils.py	121	2	98%	273–274
skore/src/skore/_sklearn/_plot/data
__init__.py	2	0	100%
table_report.py	175	1	99%	657
skore/src/skore/_sklearn/_plot/inspection
__init__.py	0	0	100%
coefficients.py	219	1	99%	294
impurity_decrease.py	61	1	98%	185
permutation_importance.py	149	0	100%
utils.py	9	0	100%
skore/src/skore/_sklearn/_plot/metrics
__init__.py	6	0	100%
confusion_matrix.py	156	0	100%
metrics_summary_display.py	8	0	100%
precision_recall_curve.py	108	0	100%
prediction_error.py	151	0	100%
roc_curve.py	112	0	100%
skore/src/skore/_sklearn/train_test_split
__init__.py	0	0	100%
train_test_split.py	58	0	100%
skore/src/skore/_sklearn/train_test_split/warning
__init__.py	8	0	100%
high_class_imbalance_too_few_examples_warning.py	19	1	94%	83
high_class_imbalance_warning.py	20	0	100%
random_state_unset_warning.py	10	0	100%
shuffle_true_warning.py	9	0	100%
stratify_is_set_warning.py	10	0	100%
time_based_column_warning.py	21	0	100%
train_test_split_warning.py	3	0	100%
skore/src/skore/_utils
__init__.py	6	2	66%	8, 13
_accessor.py	112	3	97%	38, 214, 268
_cache.py	37	0	100%
_environment.py	32	2	93%	41, 44
_fixes.py	8	0	100%
_index.py	5	0	100%
_logger.py	22	4	81%	15–17, 19
_measure_time.py	10	0	100%
_parallel.py	38	3	92%	23, 33, 124
_patch.py	21	12	42%	30, 35–39, 42–43, 46–47, 58, 60
_progress_bar.py	42	3	92%	67–68, 80
_show_versions.py	38	0	100%
_testing.py	103	11	89%	20, 29, 157, 166, 177–182, 184
skore/src/skore/_utils/repr
__init__.py	2	0	100%
base.py	54	0	100%
data.py	163	0	100%
html_repr.py	38	0	100%
rich_repr.py	81	0	100%
skore/src/skore/project
__init__.py	2	0	100%
_summary.py	75	1	98%	119
_widget.py	187	0	100%
project.py	56	0	100%
TOTAL	4292	92	97%

Tests	Skipped	Failures	Errors	Time
1629	5 💤	0 ❌	0 🔥	6m 9s ⏱️

[glemaitre]

I would prefer that we exclude the aggregate and query feature for the moment. I would like to tackle them in a separate PR.

Regarding the format, I would expect "wide" to not work in the case of comparing cross-validation report with different split numbers.

If we support this case (I would need to test to be sure), then I would prefer to have a format="auto" that would choose format="wide" in priority and when not possible fallback on the "long" format.

[glemaitre]

So a couple of thoughts:

• we will strive to not have multi-index in the return frame because it is complex to index
• if we want to have be able to distinguish split/label/output/estimator, we need to prepend some names with what data it is.
• for the comparison, we should further check if the features for each model have the same name (we should have a _has_same_features method) and not allow to go further if it is not the case.

So now, my question would be if we really allow wide format when we have more than a single column in the pivot_table because we will end-up with complex name.

@GaetandeCast What do you think.

[GaetandeCast]

I agree with the points you make @glemaitre and the solutions you propose.

To answer your question, the solution might be to use an "auto" option for the format parameter that uses wide when the number of columns is limited (I would say <= 2, it's still readable in that situation imo) and that switches to long otherwise. I would still want to let the user override that to force wide even if it's hard to read.

One could also make a point that in every case, the wide format is easier (but not necessarily easy) to read than long and therefore should be used by default.

Let me know what you think.

[Premkumar-2004]

I've completed the changes you requested (removing query and aggregate parameters, keeping only the format parameter with "wide"/"long" options). However, when I tried to rebase with the latest main branch, I encountered significant conflicts due to recent upstream changes:

PR #2346 renamed feature_importance to inspection
PR #2305 added select_k and sorting_order parameters to the frame() method
These changes conflict with my implementation since the file path changed and the frame() method signature is now different.

Could you please advise on how to proceed?
@GaetandeCast

[GaetandeCast]

@Premkumar-2004 I've solved merge conflicts for you. However there still are some unfinished discussions here. Please refrain from making too many changes and asking for reviews until we are settled on those.

Let's tackle:

• the two comments from @glemaitre that are not resolved.
• if and how we should limit the wide format when there is too much information to display.
• how to interact with the newly added sorting_order parameter. For now I put the changes of this PR after the sorting and/or selecting of the features but it's probably not the best thing to do. For the long format, the current sorting makes sense but in wide format does sorting even make sense ? Maybe if we sort by the average coefficient value across columns. Also the select_k feature will break the pivot table when the selection is different across groups.

[Premkumar-2004]

For the wide format issues:
If there are too many columns(like if columns > 20), we can throw an error telling users to switch to long format.
For sorting in wide format, sorting by mean coefficient value across columns makes sense to me.
For select_k and wide, we should error out if different groups end up with different features since the pivot won't work

[auguste-probabl]

From a discussion with @GaetandeCast :

The most complex case we want to support is a ComparisonReport of CrossValidationReport:

from sklearn.datasets import load_iris
from sklearn.linear_model import LogisticRegression
from skore import train_test_split
from skore import ComparisonReport, CrossValidationReport

X, y = load_iris(return_X_y=True)
split_data = train_test_split(X=X, y=y, random_state=42, as_dict=True)
estimator_1 = LogisticRegression(max_iter=10000, random_state=42)
estimator_2 = LogisticRegression(max_iter=10000, random_state=43)
comparison_report = ComparisonReport(
    [CrossValidationReport(estimator_1, X, y), CrossValidationReport(estimator_2, X, y)]
)
comparison_report.inspection.coefficients().frame()

with the output as of right now:

estimator  LogisticRegression_1                                         LogisticRegression_2  ...
split                         0         1         2         3         4                    0  ...
label                         0         0         0         0         0                    0  ...
feature                                                                                       ...
Intercept              9.862255  9.490178  9.203867  9.097505  9.657548             9.862255  ...
Feature #2            -2.350558 -2.357779 -2.395413 -2.364760 -2.364974            -2.350558  ...
Feature #3            -0.994196 -1.014208 -1.012199 -1.023142 -0.975954            -0.994196  ...
Feature #1             0.847198  0.858916  0.907798  0.941640  0.849863             0.847198  ...
Feature #0            -0.485465 -0.425253 -0.385390 -0.395168 -0.430971            -0.485465  ...

That table is hard to read because it's so wide, and also hard to query because the columns are a MultiIndex.

Some thoughts:

• When format="wide", aggregate by split by default, like we do in .metrics.summarize().
  • In the first iteration, force aggregation.
• Flatten MultiIndex, as already mentioned by @glemaitre.

More generally, we need to decide what wide is for:

• Prioritize readability (force more stuff, forbid more cases)? or
• Prioritize query-ability (more configurable, less readable by default)?

I think, along with @GaetandeCast, that we should go for readability. The customizability need is already addressed by format="long".

So specifically for the Comparison[CV] case, it could look something like

estimator  LogisticRegression_1_label_0 LogisticRegression_2_label_0 LogisticRegression_1_label_1 ...
feature                                                                                           ...
Intercept              9.862255 ± 0.445             9.862255 ± 0.445             9.862255 ± 0.445 ...
Feature #2             9.862255 ± 0.445             9.862255 ± 0.445             9.862255 ± 0.445 ...
Feature #3             9.862255 ± 0.445             9.862255 ± 0.445             9.862255 ± 0.445 ...
Feature #1             9.862255 ± 0.445             9.862255 ± 0.445             9.862255 ± 0.445 ...
Feature #0             9.862255 ± 0.445             9.862255 ± 0.445             9.862255 ± 0.445 ...

There is a case to be made that the ± thing goes a step too far, but it's much more readable this way.

As for the default value for format, I'm aligned with @GaetandeCast in thinking it should be "wide". Displays are for displaying something meaningful and readable. For the most complex case, when the estimators have different features, it's a bit tough but I think we should make "wide" output the same thing as "long". The default parameters should not lead to an error if we can avoid it.

Later, the query and aggregate parameters can also help us get both: sane defaults, e.g. aggregate=("mean", "std"), but also customization for the user. This will be relevant e.g. when there are many classes.

@Premkumar-2004 Thanks for your work on this; I think it would be a bit faster to push on this PR to bring it to the finish line. Hope that's okay with you. Again your work is very much appreciated.

[Premkumar-2004]

Sure, go ahead! Happy to help and thanks for the guidance on this. Let me know if you need anything else from my side.

[github-actions]

Caution

Some commits in the pull request are not signed, or GitHub is not able to verify the signature.
Please sign all your commits; you can find more information here.
Please note that when you activate commit signing, you'll need to retroactively sign your previous commits.