fix: evaluate the left tail without cancellation in stats/base/dists/cauchy/cdf

lib/node_modules/@stdlib/stats/base/dists/cauchy/cdf/lib/factory.js

@@ -73,6 +73,10 @@ function factory( x0, gamma ) {
 		if ( isnan( x ) ) {
 			return NaN;
 		}
+		// Below `z = -1`, `0.5 + atan(z)/pi` cancels more and more as `z` goes to `-infinity`; `atan2( gamma, x0-x )/pi` is the same quantity evaluated without the subtraction. Nearer the median the sum does not cancel and is the more accurate of the two...
+		if ( x-x0 < -gamma ) {
+			return ONE_OVER_PI * atan2( gamma, x0-x );
+		}
 		return ( ONE_OVER_PI * atan2( x-x0, gamma ) ) + 0.5;
 	}
 }

lib/node_modules/@stdlib/stats/base/dists/cauchy/cdf/lib/main.js

@@ -72,6 +72,10 @@ function cdf( x, x0, gamma ) {
 	) {
 		return NaN;
 	}
+	// Below `z = -1`, `0.5 + atan(z)/pi` cancels more and more as `z` goes to `-infinity`; `atan2( gamma, x0-x )/pi` is the same quantity evaluated without the subtraction. Nearer the median the sum does not cancel and is the more accurate of the two...
+	if ( x-x0 < -gamma ) {
+		return ONE_OVER_PI * atan2( gamma, x0-x );
+	}
 	return ( ONE_OVER_PI * atan2( x-x0, gamma ) ) + 0.5;
 }
 

lib/node_modules/@stdlib/stats/base/dists/cauchy/cdf/src/main.c

@@ -47,5 +47,9 @@ double stdlib_base_dists_cauchy_cdf( const double x, const double x0, const doub
 	if ( stdlib_base_is_infinite( x ) ) {
 		return ( x < 0.0 ) ? 0.0 : 1.0;
 	}
+	// Below `z = -1`, `0.5 + atan(z)/pi` cancels more and more as `z` goes to `-infinity`; `atan2( gamma, x0-x )/pi` is the same quantity evaluated without the subtraction. Nearer the median the sum does not cancel and is the more accurate of the two...
+	if ( x-x0 < -gamma ) {
+		return ONE_OVER_PI * stdlib_base_atan2( gamma, x0-x );
+	}
 	return ( ONE_OVER_PI * stdlib_base_atan2( x-x0, gamma ) ) + 0.5;
 }

lib/node_modules/@stdlib/stats/base/dists/cauchy/cdf/test/fixtures/julia/runner.jl

@@ -16,7 +16,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import Distributions: cdf, Cauchy
 import JSON
 
 """
@@ -41,9 +40,9 @@ julia> gen( x, x0, gamma, \"data.json\" );
 ```
 """
 function gen( x, x0, gamma, name )
-	z = Array{Float64}( undef, length(x) );
-	for i in eachindex(x)
-		z[ i ] = cdf( Cauchy( x0[i], gamma[i] ), x[i] );
+	# The CDF is evaluated in extended precision, as `0.5 + atan(z)/pi` cancels in double precision left of the median...
+	z = setprecision( BigFloat, 2048 ) do
+		Float64.( 0.5 .+ ( atan.( ( BigFloat.( x ) .- BigFloat.( x0 ) ) ./ BigFloat.( gamma ) ) ./ BigFloat( pi ) ) );
 	end
 
 	# Store data to be written to file as a collection:
@@ -87,3 +86,10 @@ x = rand( 1000 ) .* 2.0;
 x0 = rand( 1000 ) .* 1.0;
 gamma = rand( 1000 ) .* 50.0;
 gen( x, x0, gamma, "large_gamma.json" );
+
+# Far left tail, many orders of magnitude below the median:
+z = .-exp10.( ( rand( 1000 ) .* 290.0 ) .+ 6.0 );
+x0 = ( rand( 1000 ) .* 20.0 ) .- 10.0;
+gamma = ( rand( 1000 ) .* 10.0 ) .+ 0.1;
+x = ( z .* gamma ) .+ x0;
+gen( x, x0, gamma, "left_tail.json" );

lib/node_modules/@stdlib/stats/base/dists/cauchy/cdf/test/test.cdf.js

@@ -32,6 +32,7 @@ var cdf = require( './../lib' );
 
 var largeGamma = require( './fixtures/julia/large_gamma.json' );
 var negativeMedian = require( './fixtures/julia/negative_median.json' );
+var leftTail = require( './fixtures/julia/left_tail.json' );
 var positiveMedian = require( './fixtures/julia/positive_median.json' );
 
 
@@ -148,3 +149,22 @@ tape( 'the function evaluates the cdf for `x` given `x0` and `gamma` (`x0 > 0`)'
 	}
 	t.end();
 });
+
+tape( 'the function evaluates the cdf for `x` given `x0` and `gamma` far into the left tail', function test( t ) {
+	var expected;
+	var gamma;
+	var x0;
+	var x;
+	var y;
+	var i;
+
+	expected = leftTail.expected;
+	x = leftTail.x;
+	x0 = leftTail.x0;
+	gamma = leftTail.gamma;
+	for ( i = 0; i < x.length; i++ ) {
+		y = cdf( x[i], x0[i], gamma[i] );
+		t.strictEqual( isAlmostSameValue( y, expected[ i ], 2 ), true, 'returns expected value' );
+	}
+	t.end();
+});

lib/node_modules/@stdlib/stats/base/dists/cauchy/cdf/test/test.factory.js

@@ -32,6 +32,7 @@ var factory = require( './../lib/factory.js' );
 
 var largeGamma = require( './fixtures/julia/large_gamma.json' );
 var negativeMedian = require( './fixtures/julia/negative_median.json' );
+var leftTail = require( './fixtures/julia/left_tail.json' );
 var positiveMedian = require( './fixtures/julia/positive_median.json' );
 
 
@@ -197,3 +198,24 @@ tape( 'the created function evaluates the cdf for `x` given `x0` and `gamma` (`x
 	}
 	t.end();
 });
+
+tape( 'the created function evaluates the cdf for `x` given `x0` and `gamma` far into the left tail', function test( t ) {
+	var expected;
+	var gamma;
+	var cdf;
+	var x0;
+	var x;
+	var y;
+	var i;
+
+	expected = leftTail.expected;
+	x = leftTail.x;
+	x0 = leftTail.x0;
+	gamma = leftTail.gamma;
+	for ( i = 0; i < x.length; i++ ) {
+		cdf = factory( x0[i], gamma[i] );
+		y = cdf( x[i] );
+		t.strictEqual( isAlmostSameValue( y, expected[ i ], 2 ), true, 'returns expected value' );
+	}
+	t.end();
+});

lib/node_modules/@stdlib/stats/base/dists/cauchy/cdf/test/test.native.js

@@ -33,6 +33,7 @@ var NINF = require( '@stdlib/constants/float64/ninf' );
 
 var largeGamma = require( './fixtures/julia/large_gamma.json' );
 var negativeMedian = require( './fixtures/julia/negative_median.json' );
+var leftTail = require( './fixtures/julia/left_tail.json' );
 var positiveMedian = require( './fixtures/julia/positive_median.json' );
 
 
@@ -157,3 +158,22 @@ tape( 'the function evaluates the cdf for `x` given `x0` and `gamma` (`x0 > 0`)'
 	}
 	t.end();
 });
+
+tape( 'the function evaluates the cdf for `x` given `x0` and `gamma` far into the left tail', opts, function test( t ) {
+	var expected;
+	var gamma;
+	var x0;
+	var x;
+	var y;
+	var i;
+
+	expected = leftTail.expected;
+	x = leftTail.x;
+	x0 = leftTail.x0;
+	gamma = leftTail.gamma;
+	for ( i = 0; i < x.length; i++ ) {
+		y = cdf( x[i], x0[i], gamma[i] );
+		t.strictEqual( isAlmostSameValue( y, expected[ i ], 2 ), true, 'returns expected value' );
+	}
+	t.end();
+});