common/math: Add math.Abs to PercentageDifference calculation

[shazbert]

PR Description

• Needed absolute value as it was returning negative values.
• Adds decimal package calc
• Adds vars so that less decimal structs are allocated
• Rename CalculatePercentageGainOrLoss -> PercentageChange

Fixes # (issue)

Type of change

Please delete options that are not relevant and add an x in [] as item is complete.

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How has this been tested

Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration and
also consider improving test coverage whilst working on a certain feature or package.

• go test ./... -race
• golangci-lint run
• Test X

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation and regenerated documentation via the documentation tool
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally and on Github Actions with my changes
• Any dependent changes have been merged and published in downstream modules

[gloriousCode]

I wouldn't call it a bug to have a negative percentage difference. I would suggest you add CalculateAbsPercentageDifference and DecimalAbsPercentageDifference

[shazbert]

Yeah, I guess they are both valid so it's not a bug, but I would caution adding the difference though as you can get values above 100% in the negative direction, all we are achieving is finding the degree of magnitude, I would say directionality can be applied to the value after if needed? I see that I am starting to furiously agree with you as I type this. So I can add the distinction and people can choose their own destiny. 😆

[codecov]

Codecov Report

Attention: Patch coverage is 96.55172% with 1 line in your changes missing coverage. Please review.

Project coverage is 37.11%. Comparing base (17c2ef2) to head (bdc9646).
Report is 66 commits behind head on master.

Files with missing lines	Patch %	Lines
common/math/math.go	94.11%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1617      +/-   ##
==========================================
+ Coverage   36.37%   37.11%   +0.74%     
==========================================
  Files         422      414       -8     
  Lines      183113   180203    -2910     
==========================================
+ Hits        66602    66880     +278     
+ Misses     108466   105462    -3004     
+ Partials     8045     7861     -184     

Files with missing lines	Coverage Δ
engine/datahistory_manager.go	64.44% <100.00%> (ø)
exchanges/orderbook/calculator.go	97.23% <100.00%> (ø)
exchanges/orderbook/tranches.go	99.32% <100.00%> (ø)
common/math/math.go	79.52% <94.11%> (+0.30%)	⬆️

... and 112 files with indirect coverage changes

[gloriousCode]

itotallydidntforgetabouthitsonepleasedontbemadtACK!

[gbjk]

I've added questions and naming suggestions.
Nothing is a deal breaker, so it's Approved.

My biggest question is with the maths here.

When you say "percentage difference" this doesn't feel like something you can average.
This takes the change as a percentage difference between the average of two numbers.
Normally I'd want to know percentage increase or decrease, and I'd expect it to be the difference as a percentage of the smaller or larger number, respectively.

So I'm just noting that this feels like a subjective implementation, and without further context I just assume it suits the context.

Certainly "PercentageDifference" isn't "PercentageIncrease" so ... that's good 🤷

[gbjk]

Naming:
Admitting this was already here, but "Calculate" feels redundant.
I'd be supportive of an aggressive rename.

[shazbert]

GetPercentageDifferenceAggressively() ? 😆 What do you suggest for the name?

[gbjk]

Generally Get or Fetch should be for something you need to go and find, where it might not be obvious that you're going external to get it. Most of the time I feel they should be left out as well though.
They all talk too much about the methodology, which isn't relevant (and in some cases might change, when caching is introduced).

So just PercentageDifference or PctDiff.
I'd probably say PercentageDelta.

Note: I got saner in the main comment. DifferenceAsPercentageOfAverage

[thrasher-]

PercentageDifference is good 👍

[thrasher-]

Part of the rename can change CalculatePercentageGainOrLoss to PercentageChange to make it less specific. Then rename all funcs to have their function's purpose first. So:

PercentageChange > native
PercentageChangeDecimal > decimal etc.

I think this would be more useful for people using autocomplete features in their IDE since ATM we have a lot of prefixed DecimalX's which could spam the user with options

[shazbert]

here ya go

[shazbert]

When you say "percentage difference" this doesn't feel like something you can average.

The average is the point of reference rather than a percentage change from point A (as reference) -> point B. I think that's the main diff 😆

[gbjk]

The average is the point of reference rather than a percentage change from point A (as reference) -> point B. I think that's the main diff 😆

Alternative maths for what I'd expect this to be:

( ( max(a, b) / min( a, b) ) - 1 ) * 100
((8 / 5) - 1) * 100 = 60%

So ... I guess nail on the head is terminology.
What you're doing is DifferenceAsPercentageOfAverage
That's super long winded, but PercentageDifference really does feel like it means what percentage increase would make this happen, but it's open to mis-interpretation.
DifferenceAsPercentage would feel like it's implicitly as a percentage of the min(a, b).

• PercentageIncrease => 8 / 5 => 60% increase
• PercentageDecrease => 1 - (5 / 8) => 37.5% decrease
• DifferenceAsPercentageOfAverage => 46% ... wombles 🐻 ... 🤷

[gbjk]

Let me retract: The majority of calculators and definitions accept PercentageDifference to be a percentage of the average, so you're fine to use that terminology.

[gbjk]

One comment change. Soz.

[gbjk]

This definitely needs to say that it's of the average. All the calculators were at pains to point that out too.
Suggest:

// PercentageDifference returns difference between two numbers as a percentage of their average

[shazbert]

nice

[gbjk]

Good work 🎉