fix(search): pass groups to the splitter and fit params to the estimator

[ChrisW09]

Fixes #91.

RepresentationSearchCV could not use group splitters such as GroupKFold. fit called the splitter without groups and had no groups argument, and there was no way to pass sample_weight or other fit parameters to the estimator. Grouped data (patients, sessions, sites) could not be searched with a split that keeps each group on one side.

Root cause

RepresentationSearchCV.fit(X, y) took no other arguments. It called cv.split(np.zeros(n_samples), y_arr) without groups and fitted the estimator on each fold and at the refit with fit(x, y) only.

Fix

RepresentationSearchCV.fit is now fit(X, y=None, *, groups=None, **fit_params), as in scikit-learn's searches:

• groups is passed to cv.split.
• fit_params are made indexable once with scikit-learn's _check_method_params. Each fold's estimator gets them restricted to the fold's training rows, and the final refit of best_estimator_ gets them whole.
• The candidate Preprocessors and the scorer do not receive them, so target-aware placement and validation scores stay unweighted.

Behaviour changes

• fit accepts groups and arbitrary keyword fit parameters. Calls without them behave as before.
• Passing groups with a splitter that does not use them shows scikit-learn's usual The groups parameter is ignored by ... warning.

Documentation

• RepresentationSearchCV.fit docstring: new Parameters and Returns sections, including groups and **fit_params and who receives them.
• cv parameter docstring: a group splitter such as GroupKFold needs groups at fit.
• docs/core_concepts/target_awareness.md ("Searching over representations"): a GroupKFold example with groups=patient_id, and a paragraph explaining that fit parameters such as sample_weight reach the estimator on every fold and at the refit, but not the Preprocessor or the scorer.

Tests

• test_group_splitter_receives_groups[group_kfold], [leave_one_group_out], [group_shuffle_split]: with groups and a per-row fit parameter, each fold's estimator sees exactly the splitter's training rows, and no group is on both sides of a split. Fails on main (TypeError), passes here.
• test_groups_leave_non_group_splits_unchanged: with a splitter that ignores groups, passing groups leaves cv_results_ unchanged. Fails on main (TypeError), passes here.
• test_fit_params_are_split_per_fold_and_passed_to_the_refit: a per-row fit parameter is restricted to each fold's training rows and passed whole to the refit. Fails on main (TypeError), passes here.
• test_sample_weight_reaches_the_estimator: best_estimator_ has the coefficients of a weighted Ridge fit on the best representation, and the fold scores change with the weights. Fails on main (TypeError), passes here.

Reproduction

Output of the script from #91 on this branch:

[] -> ValueError: The 'groups' parameter should not be None.
['groups'] -> ok
['sample_weight'] -> ValueError: The 'groups' parameter should not be None.

The first and third calls give GroupKFold no groups, so they now fail in the splitter, exactly as GridSearchCV does with the same arguments. The third no longer fails with a TypeError for sample_weight. Passing groups=groups, sample_weight=np.ones(300) together fits.

Checks

• just test: 1444 passed, 59 skipped, 7 xfailed; coverage 93.65% (gate 90%).
• Minimum dependencies (CI job: Python 3.10, numpy 1.24.4, pandas 2.0.3, scipy 1.10.1, scikit-learn 1.6.0): 1431 passed, 72 skipped, 7 xfailed; scripts/quickstart.py passes.
• just docs: strict build succeeds.
• just check: all pre-commit and pre-push hooks pass (ruff format, ruff lint, prettier, file hygiene, pyright with 0 errors).
• Import direction between subpackages is unchanged.

Merge notes

• Base: main.
• The PR for RepresentationSearchCV lacks predict_proba, classes_ and classifier tags, so nested roc_auc CV returns NaN #92 (fix(search): make the search a classifier when it wraps a classifier #127) conflicts in three files. In pretab/compose/search.py, keep _check_method_params in the sklearn.utils.validation import next to RepresentationSearchCV lacks predict_proba, classes_ and classifier tags, so nested roc_auc CV returns NaN #92's get_tags and available_if imports. At the refit, keep fit(x_all, y_arr, **fit_params) followed by RepresentationSearchCV lacks predict_proba, classes_ and classifier tags, so nested roc_auc CV returns NaN #92's n_features_in_ and feature_names_in_ lines. In docs/core_concepts/target_awareness.md, both add paragraphs after the search example: keep both, this PR's first. In tests/compose/test_search.py, merge the imports and keep both test blocks. Resolved this way, the full suite passes (1450 passed, 59 skipped, 7 xfailed).
• The PR for Preprocessor rejects polars DataFrames, so pipelines with set_output(transform="polars") crash #94 (fix(preprocessor): accept polars DataFrames as input #129) conflicts in the signature and docstring of RepresentationSearchCV.fit. Keep this PR's signature and parameter sections and add Preprocessor rejects polars DataFrames, so pipelines with set_output(transform="polars") crash #94's paragraph on polars input. Preprocessor rejects polars DataFrames, so pipelines with set_output(transform="polars") crash #94's one-time polars conversion then runs before _check_method_params. Resolved this way, the full suite passes (1460 passed, 59 skipped, 7 xfailed).
• The PR for RepresentationSearchCV with a classifier uses task="regression" for placement; string labels crash #77 (fix(search): default to the classification task for a classifier #115) merges cleanly in pretab/compose/search.py. tests/compose/test_search.py has an append/append conflict: keep both blocks.

This change was previously part of #97, which is closed in favour of one pull request per issue.