deprecate derivatives and error_components

[jagerber48]

• Closes # (insert issue number)
• Executed pre-commit run --all-files with no errors
• The change is fully covered by automated unit tests
• Documented in docs/ as appropriate
• Added an entry to the CHANGES file

.

• Marks AffineScalarFunc.derivatives propert as deprecated
• Marks AffineScalarFunc.error_components() as deprecated and that it will be replaced with a property AffineScalarFunc.error_components.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.17%. Comparing base (a67959d) to head (18b68f4).
⚠️ Report is 12 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #337      +/-   ##
==========================================
+ Coverage   87.15%   87.17%   +0.01%     
==========================================
  Files          20       20              
  Lines        2017     2019       +2     
==========================================
+ Hits         1758     1760       +2     
  Misses        259      259              

Flag	Coverage Δ
macos-latest-3.10	95.64% <100.00%> (+<0.01%)	⬆️
macos-latest-3.11	95.64% <100.00%> (+<0.01%)	⬆️
macos-latest-3.12	95.64% <100.00%> (+<0.01%)	⬆️
macos-latest-3.13	95.64% <100.00%> (+<0.01%)	⬆️
macos-latest-3.14	95.64% <100.00%> (+<0.01%)	⬆️
macos-latest-3.8	95.64% <100.00%> (+<0.01%)	⬆️
macos-latest-3.9	95.64% <100.00%> (+<0.01%)	⬆️
no-numpy	82.51% <100.00%> (+0.01%)	⬆️
ubuntu-latest-3.10	95.64% <100.00%> (+<0.01%)	⬆️
ubuntu-latest-3.11	95.64% <100.00%> (+<0.01%)	⬆️
ubuntu-latest-3.12	95.64% <100.00%> (+<0.01%)	⬆️
ubuntu-latest-3.13	95.64% <100.00%> (+<0.01%)	⬆️
ubuntu-latest-3.14	95.64% <100.00%> (+<0.01%)	⬆️
ubuntu-latest-3.8	95.64% <100.00%> (+<0.01%)	⬆️
ubuntu-latest-3.9	95.64% <100.00%> (+<0.01%)	⬆️
windows-latest-3.10	95.64% <100.00%> (+<0.01%)	⬆️
windows-latest-3.11	95.64% <100.00%> (+<0.01%)	⬆️
windows-latest-3.12	95.64% <100.00%> (+<0.01%)	⬆️
windows-latest-3.13	95.64% <100.00%> (+<0.01%)	⬆️
windows-latest-3.14	95.64% <100.00%> (+<0.01%)	⬆️
windows-latest-3.8	95.64% <100.00%> (+<0.01%)	⬆️
windows-latest-3.9	95.64% <100.00%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ 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.

[codspeed-hq]

CodSpeed Performance Report

Merging #337 will not alter performance

_{Comparing jagerber48:deprecate_derivatives_and_error_components (18b68f4) with master (a67959d)}

Summary

✅ 5 untouched

[jagerber48]

This PR is ready for review

[jagerber48]

@newville @wshanks @andrewgsavage this small PR is ready for review. These two attributes are being either removed or changed in 4.0 so we need to mark them as deprecated in a 3.x release.

[jagerber48]

@newville @wshanks @andrewgsavage bump again, looking for feedback on the wording. If I don't hear anything in a week I'll probably move towards merging it myself.

[newville]

@jagerber48 sorry for the delay, this has a been a very busy time for me. I think this is fine, and agree the focus here should emphasize uncertainty propagation, and that the new design with UAtom and without AffineScalarFunc is better. I also don't see a lot of values in "derivatives" here, except as they are used for uncertainty propagation.

In fact, I think the "implied function/property" or "action at a distance" of:

>>> from uncertainties import ufloat
>>> a = ufloat(1, 0.2)
>>> b = a * 2
>>> b
2.0+/-0.4
>>> a.std_dev = 0.5
>>> b
2.0+/-1.0

in which b is an AffineScalerFunc (emphasis on "Func" and evaluated each time it is accessed), is more of a "wart" than a "valuable feature".

[newville]

I think this is good, but (of course) @wshanks should be satisfied before merging.

[jagerber48]

@jagerber48 sorry for the delay, this has a been a very busy time for me. I think this is fine, and agree the focus here should emphasize uncertainty propagation, and that the new design with UAtom and without AffineScalarFunc is better. I also don't see a lot of values in "derivatives" here, except as they are used for uncertainty propagation.

In fact, I think the "implied function/property" or "action at a distance" of:

>>> from uncertainties import ufloat
>>> a = ufloat(1, 0.2)
>>> b = a * 2
>>> b
2.0+/-0.4
>>> a.std_dev = 0.5
>>> b
2.0+/-1.0

in which b is an AffineScalerFunc (emphasis on "Func" and evaluated each time it is accessed), is more of a "wart" than a "valuable feature".

Yeah, this behavior is highly undesirable. Another issue is that you can set std_dev on a, but if you try to set it on b you get an AttributeError. Not to mention the action-at-a-distance. In 4.0.0 it will not be possible to set std_dev on a UFloat. UFloat instances are totally immutable except for the fact that the std_dev of the UCombo at UFloat._uncertainty is lazily evaluated.

[jagerber48]

@wshanks @newville This PR is ready for review and merge if it looks good. I keep messing up the stacklevel on these warnings, so a double check I did the right thing here would be appreciated.

[wshanks]

stacklevel looks good to me. I do agree that this has been a long process and we should move forward.

I don't love the lack of a migration path for error_components (no easy way to update code so it works in v3 and v4) but we expect not too many people to be affected so we can just accept some disruption there.

[newville]

@jagerber48 @wshanks Thanks - I agree all around. I have always found the integer stacklevel in warn() confusing, but I think the stacklevel=2 is the best choice here: The AffineScalarFunc should be shown as the deprecating object....

I will just go for it and rebase and merge. Yay!

[jagerber48]

stacklevel looks good to me. I do agree that this has been a long process and we should move forward.

I don't love the lack of a migration path for error_components (no easy way to update code so it works in v3 and v4) but we expect not too many people to be affected so we can just accept some disruption there.

@wshanks
Yeah.. I think what you're looking for is a way to make it so that users can do x.error_components() AND x.error_components in 3.2.4 getting the same result. That way users can safely update their code while staying <4.0 then migrate to 4.0 after things check out. Unfortunately I don't know if it's possible to do that syntactically in python while keeping the exact same name and without returning a modified dict like you had suggested earlier. And that is a high level of wonkiness not worth the level of pain to a small number of users to migrate. So I think giving the deprecation warning in 3.2.4 then making a hard change in 4.0 is l we can do.

Fortunately the change is very easy to fix, just remove ().