This one is ready for a first review - but we need to make some decisions, listed above, so I would be very glad of some initial feedback.

I'll proceed with these (provisional) answers to the points for discussion above:

• from_estimate is a reasonable name for the class constructor method. Conversely, using estimate will commit us to using a odd trick that allows the class method to differ from the instance method - contrary to the normal interface in Python - and for the long term (because we will have to keep an error marker for the instance method).
• I believe my check for the degenerate transform is (now) correct (directly evaluate the determinant of the generated transform matrix).
• I guess that the use-case is rare, of investigating the various affines in a PiecewiseAffineTransform, and that rare user that needs to investigate, can read the code for themselves to reproduce the steps. So None is OK as a return value from from_estimate. If it proves necessary to get the component affines, we can add that as another class method, I guess. But not in this PR, as likely YAGNI.
• I will implement from_estimate and estimate deprecations for LineModelND, CircleModel, EllipseModel andThinPlateSpline.

When I've done the last step, I'll unmark this PR as draft.

If anyone disagrees with the above - let me know soon?

That all sounds good to me. I'm fine with from_estimate. I do think we need a way to tell the user whether the transform succeeded or failed in all cases. Raising may be a fine option, unless there is some reason to proceed with a non-fitted model.

I do think we need a way to tell the user whether the transform succeeded or failed in all cases

Could you say more about what you were getting at here?

Nevermind, I had misunderstood what you wrote. I guess the question is: do we return None on failure, or error out? It may be unexpected to get a non-Transform-class-compliant result without obvious failure.

From reading through this, I concur with the general direction.

Re failed estimations, if feel like returning None isn't a bad choice on failed estimation, but it might be unexpected for users. What do you think about using try_estimate instead of from_estimate? try_ would clearly indicate, hey this may fail and there's behavior for it.

Exceptions might work too, but a try except block forces users to check what kind of exception is raised. We could provide that optionally but I wouldn't make it the default.

I like that from_estimate conveys that we are making a transform from an estimate - it has a classic class constructor feel. Whereas try_estimate feels like it will trigger some confusion - is this like a try ... except?

I have a vague positivity about the current API - in that there is no way that someone could accidentally use a None returned Transform. For the option of raising an error - we really aren't saving them that much code. I mean comparing:

tf = AffineTransform.from_estimate(src, dst, raise_on_failure=True)

to:

tf = AffineTransform(src, dst):
if tf is None: raise ValueError('Estimation failed')

Matthew, re: the None return: it's not that it's hard to handle, more that it hides failures in a way that may not be obvious to developers. E.g., if you run a program and it works fine the first ten times, but then the 11th time breaks because None doesn't have some attribute, it's going to be confusing. If the error is "we couldn't fit the model", you immediately know what went wrong.

Re: naming, I prefer from_estimate, since that's already a paradigm in pandas etc.

Re #7771 (comment), I can live happily with from_estimate. 😄

Regarding raising on failure, this would be a way to tell users why an estimation failed. Just returning None has a "computer says no" vibe. 😅 But we could also work with warnings instead. Or add optional and more specific exceptions later. So I'm happy to keep this out of the scope of this PR.

Matthew, re: the None return: it's not that it's hard to handle, more that it hides failures in a way that may not be obvious to developers. E.g., if you run a program and it works fine the first ten times, but then the 11th time breaks because None doesn't have some attribute, it's going to be confusing. If the error is "we couldn't fit the model", you immediately know what went wrong.

Re: naming, I prefer from_estimate, since that's already a paradigm in pandas etc.

I'm happy with raising an error in the class method instead - that was my original implementation. Would you prefer that?

As always with API design, I just have a vague feeling, so I'll have to rely on y'all to help me figure out if the concern is legit or not.

Could we perhaps use a nice sentinel value other than None? That should result in nice error messages like "<FailedEstimation> has no attribute...". I would also provide a nice container for a string giving a reason for the failure. Though, we would need a good to check this maybe with something like

class FailedEstimation:
    def __bool__(self):
        return False

that would still allow a simple if not tform: check or assert tform.

Could we perhaps use a nice sentinel value other than None? That should result in nice error messages like " has no attribute...". I would also provide a nice container for a string giving a reason for the failure. Though, we would need a good to check this maybe with something like

class FailedEstimation:
    def __bool__(self):
        return False

that would still allow a simple if not tform: check or assert tform.

What would be the advantage over raising an error?

What would be the advantage over raising an error?

As stated above, it's easier to handle. try...except forces users to lookup and match the correct exception. But perhaps still better than a weird custom object that is "falsy".

What would be the advantage over raising an error?

As stated above, it's easier to handle. try...except forces users to lookup and match the correct exception. But perhaps still better than a weird custom object that is "falsy".

Ah yes - sorry - I see the point. I guess at the moment, my order of preference is:

• falsey return value (@lagru's suggestion). I guess we could add an error message there, perhaps returned by __str__.
• raise an error in class constructor.
• None return value.

but I don't feel very strongly. What do y'all think?

Returning to the API question ... it seems to me that one will often want to do this, as @lagru points out:

tf = Transform.from_estimate(src, dst)
if not tf:
    "Respond in some way"

So far, the None and FailedEstimation ideas both serve. The FailedEstimation improves on None in allowing - say - a .message to give more information, at the expense of being a bit more fancy and less obvious.

Otherwise (the raise option), one will nearly always have to do something like:

try:
    tf = Transform.from_estimate(src, dst)
except TransformEstimationError:
    "Respond in some way"

Of course, we could give the user a choice with:

 tf = Transform.from_estimate(src, dst, raise=True)

where the user then passes on the problem to their user. But this seems like an example where "There should be one-- and preferably only one --obvious way to do it." And we aren't saving the user much compared to:

tf = Transform.from_estimate(src, dst)
if not tf:
    "Respond in some way"

The advantage of Lars' FailedEstimation is that the user can even do:

tf = Transform.from_estimate(src, dst)
if not tf:
    raise ErrorOfYourChoice(str(tf))

So I'm still vaguely in favor of Lars' FailedEstimation idea. Any more thoughts?

As a side-point, and returning to this item:

• I guess that the use-case is rare, of investigating the various affines in a PiecewiseAffineTransform, and that rare user that needs to investigate, can read the code for themselves to reproduce the steps. So None is OK as a return value from from_estimate. If it proves necessary to get the component affines, we can add that as another class method, I guess. But not in this PR, as likely YAGNI.

Lar's FailedEstimate allows us a simple way to return the intermediate results of the failed estimation, if we want to do that.

@lagru - you mentioned resolving the stacklevel for the warnings. I wonder whether you could help me with some confusing stacklevel test errors? Example at https://github.com/matthew-brett/scikit-image/actions/runs/14408547193/job/40410880036#step:9:445:

        warning_message = (
            "Standard deviation of data is too small to estimate "
            "circle with meaningful precision."
        )
        with pytest.warns(RuntimeWarning, match=warning_message) as _warnings:
            assert CircleModel.from_estimate(np.ones((6, 2))) is None
>       assert_stacklevel(_warnings)
E       AssertionError: Warning with wrong stacklevel:
E         Expected: /opt/hostedtoolcache/Python/3.13.2/x64/lib/python3.13/site-packages/skimage/measure/tests/test_fit.py:190
E         Actual: /opt/hostedtoolcache/Python/3.13.2/x64/lib/python3.13/site-packages/skimage/_shared/utils.py:572
E         RuntimeWarning: Standard deviation of data is too small to estimate circle with meaningful precision.

This appears to be because I'm using the now-deprecated estimate method from the from_estimate class method, and ignoring the warning on the way:

    @classmethod
    def from_estimate(cls, data):
        instance = cls()
        with catch_warnings():
            filterwarnings("ignore", message="`estimate` is deprecated")
            success = instance.estimate(data)
        return instance if success else None

but I must admit I didn't understand the stacklevel code in _shared/utils.py. Do you see what the problem is?

OK - work now basically done, waiting for a decision on the return value from the from_estimate class methods. Any final words? Otherwise I'll implement @lagru's suggestion.

Failures appear unrelated. OK to pass this ball back to you @lagru?

I added the missing TODO.txt notes and updated the release notes in the PR summary, adding a bit more details and justification. This should be good to go.

🎉