Deprecate positional treatment/y across all learners for sklearn Pipeline compat (#854)

[jeongyoonlee]

What & why

Kicks off #854 — making CausalML's learners compatible with sklearn.pipeline.Pipeline, the one intentional breaking change on the v1.0 roadmap (M1).

Pipeline calls the final estimator's fit(X, y) positionally, but CausalML learners take fit(X, treatment, y, ...) — y is third. In v1.0 the positional order becomes (X, y, treatment, ...).

Reordering two required positional arguments can't be done in one step without risking a silent y/treatment swap for existing positional callers. So this is a two-step deprecation, and this PR is step one (non-breaking):

• Positional order is unchanged. Every existing fit(X, treatment, y) call keeps working exactly as before.
• Passing treatment/y positionally now emits a FutureWarning pointing callers to keyword arguments: fit(X, y=y, treatment=treatment). Keyword calls are order-independent, so code that migrates now keeps working unchanged across the v1.0 flip.
• Step two (a later PR, targeted at v1.0): flip the positional signatures and drop the shim — tracked as Flip every signature to (X, y, treatment, ...) and delete the deprecation shim #985 on epic Adopt the scikit-learn fit(X, y, treatment, ...) argument order (v1.0 M1) #980.

A deprecation window is one-shot: anything whose positional order changes at v1.0 has to warn in this release, or it needs a second cycle of its own. That is the constraint that sets this PR's scope — the warning has to be complete now, even though the flip is still a PR away.

How

• causalml/inference/_arg_order.py holds a re-entrancy-guarded decorator that derives each method's v1.0 order from its own signature: X, then y, then treatment, with every other parameter keeping its relative position. Each warning names that method's real target order rather than assuming (X, treatment, y, ...), so BaseDRIVLearner.fit reports (X, y, treatment, assignment, ...) and IVRegressor.fit reports (X, y, treatment, w).
• Coverage is decided by signature, not by method name. Any method whose positional order would change is shimmed. An earlier draft of this PR used a four-name allowlist (fit / fit_predict / estimate_ate / predict) and silently missed eleven public methods (Extend the #854 deprecation shim to the remaining public treatment-before-y methods #981) — see Scope below.
• __init_subclass__ lives on SerializableLearner, the shared mixin, so one hook covers the meta-learners, the causal/uplift trees and forests, and the IV learners with no per-method edits. functools.wraps preserves the real signatures for introspection and sklearn metadata routing.
• Classes outside that hierarchy — TF/JAX DragonNet, Torch/JAX CEVAE, PolicyLearner, TMLELearner, Sensitivity — apply the same decorator at the class level.
• The guard ensures internal delegation — fit_predict → fit/predict, subclass fit → super().fit(X, treatment, y, *args, **kwargs), estimate_ate → fit_predict → fit — warns at most once per top-level call.
• No internal call sites needed changing: CausalML's own code (metrics/sensitivity.py, dataset/synthetic.py, …) already calls these methods with keywords.

Scope

• In: every method whose positional order changes at v1.0. That is the whole fit family plus predict, and also bootstrap, fit_bootstrap_ensemble, bootstrap_pool, prune, fill, and the three Sensitivity.get_* helpers — eleven public methods that a name-based allowlist had missed (Extend the #854 deprecation shim to the remaining public treatment-before-y methods #981). Package-wide, nothing whose order changes is left unshimmed, and a test enforces that.
• predict is in scope. Its current (X, treatment, y, ...) doesn't block Pipeline, since predict(X) already works. But flipping only fit would leave v1.0 with the same two arguments in opposite positional orders on one class — fit(X, y, treatment) beside predict(X, treatment, y) — with no TypeError to catch a swap. Methods that don't take both treatment and y, such as BaseRLearner.predict, are left untouched.
• The trees are deliberately included. CausalTreeRegressor and the forests already inherit sklearn's BaseDecisionTree/ForestRegressor and override fit(X, y, ...) with fit(X, treatment, y, ...). Leaving them out would ship v1.0 with the most sklearn-shaped classes keeping the least sklearn-shaped signature.
• UpliftTreeClassifier's validation triple is reordered in place (epic Adopt the scikit-learn fit(X, y, treatment, ...) argument order (v1.0 M1) #980, open question 1), so it stays consistent with the main one: (X, y, treatment, X_val, y_val, treatment_val, ...).
• The Sensitivity helpers are in scope (epic Adopt the scikit-learn fit(X, y, treatment, ...) argument order (v1.0 M1) #980, open question 2). Theirs is a third argument shape — (X, p, treatment, y) — and becomes (X, y, treatment, p).
• Note: reordering alone doesn't make a learner a drop-in Pipeline step — treatment still needs to be threaded via sklearn metadata routing, tracked as sklearn metadata routing: let treatment reach a learner inside a Pipeline #986. CausalML is not compatible with Scikit-Learn Pipeline #854 stays open until that lands.
• Follow-up, not in this PR: CausalML's own tests and docs call these methods positionally in many places and are now the loudest consumers of the new warning. Migrating them is Migrate tests/ to keyword fit/predict calls (917 FutureWarnings) #982 and Migrate docs notebooks and guides to keyword fit/predict calls #983 — those call sites are also what would break at the flip.

Two incidental fixes

Both were required to make the above work, and both are visible in the diff:

• causalml/inference/tree/utils.py::timeit now uses functools.wraps. Without it, CausalTreeRegressor.bootstrap_pool — its only user — reported (*args, **kw) to inspect.signature and "wrapped" as its __name__, which is exactly what hid it from a signature-based shim. Pre-existing bug; it also means anything introspecting that method, sklearn included, was seeing the wrong signature.
• v1_order reorders only when both y and treatment are present. Hoisting y on its own reached the vendored sklearn tree builders (build(tree, X, y, ...), where y would land ahead of X) and SemiSynthDataGenerator.fit(X, w, y, ...), whose treatment vector is named w. Both are pinned as regression cases.

Tests

tests/test_fit_arg_order.py (52 cases): positional-use warning across S/T/X/R/DR and the classifier variants, keyword silence, single-warning delegation (fit_predict / estimate_ate / subclass super().fit), signature preservation, positional == keyword equivalence (guards against a silent y/treatment swap), predict warning/silence, bootstrap warning, the v1.0 ordering rule itself (DRIV's assignment, the uplift validation triple, the Sensitivity shape, and the two cases that must not move), and behaviour on CausalTreeRegressor / IVRegressor.

Two completeness guards walk the installed package: one fails if any public method's order would change without the shim, the other fails if coverage regresses to a fixed list of method names. They cover the optional backends only in the lanes where those backends are installed.

Full local run: 418 passed, 10 skipped.

Refs #854. Part of epic #980; closes #981.