3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
4 <title>The Incomplete Beta Function Inverses</title>
5 <link rel="stylesheet" href="../../math.css" type="text/css">
6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
7 <link rel="home" href="../../index.html" title="Math Toolkit 2.11.0">
8 <link rel="up" href="../sf_beta.html" title="Beta Functions">
9 <link rel="prev" href="ibeta_function.html" title="Incomplete Beta Functions">
10 <link rel="next" href="beta_derivative.html" title="Derivative of the Incomplete Beta Function">
12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13 <table cellpadding="2" width="100%"><tr>
14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
15 <td align="center"><a href="../../../../../../index.html">Home</a></td>
16 <td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
19 <td align="center"><a href="../../../../../../more/index.htm">More</a></td>
22 <div class="spirit-nav">
23 <a accesskey="p" href="ibeta_function.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_beta.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="beta_derivative.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
26 <div class="titlepage"><div><div><h3 class="title">
27 <a name="math_toolkit.sf_beta.ibeta_inv_function"></a><a class="link" href="ibeta_inv_function.html" title="The Incomplete Beta Function Inverses">The Incomplete
28 Beta Function Inverses</a>
29 </h3></div></div></div>
30 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">beta</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
32 <pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
34 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">></span>
35 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibeta_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">);</span>
37 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">></span>
38 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibeta_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&);</span>
40 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T4</span><span class="special">></span>
41 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibeta_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">T4</span><span class="special">*</span> <span class="identifier">py</span><span class="special">);</span>
43 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T4</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">></span>
44 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibeta_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">T4</span><span class="special">*</span> <span class="identifier">py</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&);</span>
46 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">></span>
47 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibetac_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">q</span><span class="special">);</span>
49 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">></span>
50 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibetac_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">q</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&);</span>
52 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T4</span><span class="special">></span>
53 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibetac_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">q</span><span class="special">,</span> <span class="identifier">T4</span><span class="special">*</span> <span class="identifier">py</span><span class="special">);</span>
55 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T4</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">></span>
56 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibetac_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">q</span><span class="special">,</span> <span class="identifier">T4</span><span class="special">*</span> <span class="identifier">py</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&);</span>
58 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">></span>
59 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibeta_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">);</span>
61 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">></span>
62 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibeta_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&);</span>
64 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">></span>
65 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibetac_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">q</span><span class="special">);</span>
67 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">></span>
68 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibetac_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">q</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&);</span>
70 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">></span>
71 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibeta_invb</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">);</span>
73 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">></span>
74 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibeta_invb</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&);</span>
76 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">></span>
77 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibetac_invb</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">q</span><span class="special">);</span>
79 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">></span>
80 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibetac_invb</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">q</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&);</span>
82 <span class="special">}}</span> <span class="comment">// namespaces</span>
85 <a name="math_toolkit.sf_beta.ibeta_inv_function.h0"></a>
86 <span class="phrase"><a name="math_toolkit.sf_beta.ibeta_inv_function.description"></a></span><a class="link" href="ibeta_inv_function.html#math_toolkit.sf_beta.ibeta_inv_function.description">Description</a>
89 There are six <a href="http://functions.wolfram.com/GammaBetaErf/" target="_top">incomplete
90 beta function inverses</a> which allow you solve for any of the three
91 parameters to the incomplete beta, starting from either the result of the
92 incomplete beta (p) or its complement (q).
95 The final <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a> argument is optional and can
96 be used to control the behaviour of the function: how it handles errors,
97 what level of precision to use etc. Refer to the <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">policy
98 documentation for more details</a>.
100 <div class="tip"><table border="0" summary="Tip">
102 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../doc/src/images/tip.png"></td>
103 <th align="left">Tip</th>
105 <tr><td align="left" valign="top">
107 When people normally talk about the inverse of the incomplete beta function,
108 they are talking about inverting on parameter <span class="emphasis"><em>x</em></span>. These
109 are implemented here as <code class="computeroutput"><span class="identifier">ibeta_inv</span></code>
110 and <code class="computeroutput"><span class="identifier">ibetac_inv</span></code>, and are
111 by far the most efficient of the inverses presented here.
114 The inverses on the <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>b</em></span> parameters
115 find use in some statistical applications, but have to be computed by rather
116 brute force numerical techniques and are consequently several times slower.
117 These are implemented here as <code class="computeroutput"><span class="identifier">ibeta_inva</span></code>
118 and <code class="computeroutput"><span class="identifier">ibeta_invb</span></code>, and complement
119 versions <code class="computeroutput"><span class="identifier">ibetac_inva</span></code> and
120 <code class="computeroutput"><span class="identifier">ibetac_invb</span></code>.
125 The return type of these functions is computed using the <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
126 type calculation rules</em></span></a> when called with arguments T1...TN
129 <pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">></span>
130 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibeta_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">);</span>
132 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">></span>
133 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibeta_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&);</span>
135 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T4</span><span class="special">></span>
136 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibeta_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">T4</span><span class="special">*</span> <span class="identifier">py</span><span class="special">);</span>
138 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T4</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">></span>
139 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibeta_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">T4</span><span class="special">*</span> <span class="identifier">py</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&);</span>
142 Returns a value <span class="emphasis"><em>x</em></span> such that: <code class="computeroutput"><span class="identifier">p</span>
143 <span class="special">=</span> <span class="identifier">ibeta</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span>
144 <span class="identifier">b</span><span class="special">,</span> <span class="identifier">x</span><span class="special">);</span></code> and
145 sets <code class="computeroutput"><span class="special">*</span><span class="identifier">py</span>
146 <span class="special">=</span> <span class="number">1</span> <span class="special">-</span> <span class="identifier">x</span></code> when
147 the <code class="computeroutput"><span class="identifier">py</span></code> parameter is provided
148 and is non-null. Note that internally this function computes whichever is
149 the smaller of <code class="computeroutput"><span class="identifier">x</span></code> and <code class="computeroutput"><span class="number">1</span><span class="special">-</span><span class="identifier">x</span></code>,
150 and therefore the value assigned to <code class="computeroutput"><span class="special">*</span><span class="identifier">py</span></code> is free from cancellation errors. That
151 means that even if the function returns <code class="computeroutput"><span class="number">1</span></code>,
152 the value stored in <code class="computeroutput"><span class="special">*</span><span class="identifier">py</span></code>
153 may be non-zero, albeit very small.
156 Requires: <span class="emphasis"><em>a,b > 0</em></span> and <span class="emphasis"><em>0 <= p <= 1</em></span>.
159 The final <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a> argument is optional and can
160 be used to control the behaviour of the function: how it handles errors,
161 what level of precision to use etc. Refer to the <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">policy
162 documentation for more details</a>.
164 <pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">></span>
165 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibetac_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">q</span><span class="special">);</span>
167 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">></span>
168 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibetac_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">q</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&);</span>
170 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T4</span><span class="special">></span>
171 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibetac_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">q</span><span class="special">,</span> <span class="identifier">T4</span><span class="special">*</span> <span class="identifier">py</span><span class="special">);</span>
173 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T4</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">></span>
174 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibetac_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">q</span><span class="special">,</span> <span class="identifier">T4</span><span class="special">*</span> <span class="identifier">py</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&);</span>
177 Returns a value <span class="emphasis"><em>x</em></span> such that: <code class="computeroutput"><span class="identifier">q</span>
178 <span class="special">=</span> <span class="identifier">ibetac</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span>
179 <span class="identifier">b</span><span class="special">,</span> <span class="identifier">x</span><span class="special">);</span></code> and
180 sets <code class="computeroutput"><span class="special">*</span><span class="identifier">py</span>
181 <span class="special">=</span> <span class="number">1</span> <span class="special">-</span> <span class="identifier">x</span></code> when
182 the <code class="computeroutput"><span class="identifier">py</span></code> parameter is provided
183 and is non-null. Note that internally this function computes whichever is
184 the smaller of <code class="computeroutput"><span class="identifier">x</span></code> and <code class="computeroutput"><span class="number">1</span><span class="special">-</span><span class="identifier">x</span></code>,
185 and therefore the value assigned to <code class="computeroutput"><span class="special">*</span><span class="identifier">py</span></code> is free from cancellation errors. That
186 means that even if the function returns <code class="computeroutput"><span class="number">1</span></code>,
187 the value stored in <code class="computeroutput"><span class="special">*</span><span class="identifier">py</span></code>
188 may be non-zero, albeit very small.
191 Requires: <span class="emphasis"><em>a,b > 0</em></span> and <span class="emphasis"><em>0 <= q <= 1</em></span>.
194 The final <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a> argument is optional and can
195 be used to control the behaviour of the function: how it handles errors,
196 what level of precision to use etc. Refer to the <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">policy
197 documentation for more details</a>.
199 <pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">></span>
200 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibeta_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">);</span>
202 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">></span>
203 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibeta_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&);</span>
206 Returns a value <span class="emphasis"><em>a</em></span> such that: <code class="computeroutput"><span class="identifier">p</span>
207 <span class="special">=</span> <span class="identifier">ibeta</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span>
208 <span class="identifier">b</span><span class="special">,</span> <span class="identifier">x</span><span class="special">);</span></code>
211 Requires: <span class="emphasis"><em>b > 0</em></span>, <span class="emphasis"><em>0 < x < 1</em></span>
212 and <span class="emphasis"><em>0 <= p <= 1</em></span>.
215 The final <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a> argument is optional and can
216 be used to control the behaviour of the function: how it handles errors,
217 what level of precision to use etc. Refer to the <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">policy
218 documentation for more details</a>.
220 <pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">></span>
221 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibetac_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">);</span>
223 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">></span>
224 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibetac_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&);</span>
227 Returns a value <span class="emphasis"><em>a</em></span> such that: <code class="computeroutput"><span class="identifier">q</span>
228 <span class="special">=</span> <span class="identifier">ibetac</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span>
229 <span class="identifier">b</span><span class="special">,</span> <span class="identifier">x</span><span class="special">);</span></code>
232 Requires: <span class="emphasis"><em>b > 0</em></span>, <span class="emphasis"><em>0 < x < 1</em></span>
233 and <span class="emphasis"><em>0 <= q <= 1</em></span>.
236 The final <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a> argument is optional and can
237 be used to control the behaviour of the function: how it handles errors,
238 what level of precision to use etc. Refer to the <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">policy
239 documentation for more details</a>.
241 <pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">></span>
242 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibeta_invb</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">);</span>
244 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">></span>
245 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibeta_invb</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&);</span>
248 Returns a value <span class="emphasis"><em>b</em></span> such that: <code class="computeroutput"><span class="identifier">p</span>
249 <span class="special">=</span> <span class="identifier">ibeta</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span>
250 <span class="identifier">b</span><span class="special">,</span> <span class="identifier">x</span><span class="special">);</span></code>
253 Requires: <span class="emphasis"><em>a > 0</em></span>, <span class="emphasis"><em>0 < x < 1</em></span>
254 and <span class="emphasis"><em>0 <= p <= 1</em></span>.
257 The final <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a> argument is optional and can
258 be used to control the behaviour of the function: how it handles errors,
259 what level of precision to use etc. Refer to the <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">policy
260 documentation for more details</a>.
262 <pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">></span>
263 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibetac_invb</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">);</span>
265 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">></span>
266 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">ibetac_invb</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&);</span>
269 Returns a value <span class="emphasis"><em>b</em></span> such that: <code class="computeroutput"><span class="identifier">q</span>
270 <span class="special">=</span> <span class="identifier">ibetac</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span>
271 <span class="identifier">b</span><span class="special">,</span> <span class="identifier">x</span><span class="special">);</span></code>
274 Requires: <span class="emphasis"><em>a > 0</em></span>, <span class="emphasis"><em>0 < x < 1</em></span>
275 and <span class="emphasis"><em>0 <= q <= 1</em></span>.
278 The final <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a> argument is optional and can
279 be used to control the behaviour of the function: how it handles errors,
280 what level of precision to use etc. Refer to the <a class="link" href="../../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">policy
281 documentation for more details</a>.
284 <a name="math_toolkit.sf_beta.ibeta_inv_function.h1"></a>
285 <span class="phrase"><a name="math_toolkit.sf_beta.ibeta_inv_function.accuracy"></a></span><a class="link" href="ibeta_inv_function.html#math_toolkit.sf_beta.ibeta_inv_function.accuracy">Accuracy</a>
288 The accuracy of these functions should closely follow that of the regular
289 forward incomplete beta functions. However, note that in some parts of their
290 domain, these functions can be extremely sensitive to changes in input, particularly
291 when the argument <span class="emphasis"><em>p</em></span> (or it's complement <span class="emphasis"><em>q</em></span>)
292 is very close to <code class="computeroutput"><span class="number">0</span></code> or <code class="computeroutput"><span class="number">1</span></code>.
295 Comparisons to other libraries are shown below, note that our test data exercises
296 some rather extreme cases in the incomplete beta function which many other
297 libraries fail to handle:
300 <a name="math_toolkit.sf_beta.ibeta_inv_function.table_ibeta_inv"></a><p class="title"><b>Table 8.22. Error rates for ibeta_inv</b></p>
301 <div class="table-contents"><table class="table" summary="Error rates for ibeta_inv">
314 GNU C++ version 7.1.0<br> linux<br> double
319 GNU C++ version 7.1.0<br> linux<br> long double
324 Sun compiler version 0x5150<br> Sun Solaris<br> long double
329 Microsoft Visual C++ version 14.1<br> Win32<br> double
336 Inverse incomplete beta
341 <span class="blue">Max = 11ε (Mean = 0.345ε)</span><br> <br>
342 (<span class="emphasis"><em>Rmath 3.2.3:</em></span> <span class="red">Max = 1.14e+121ε (Mean
343 = 3.28e+119ε) <a class="link" href="../logs_and_tables/logs.html#errors_GNU_C_version_7_1_0_linux_double_ibeta_inv_Rmath_3_2_3_Inverse_incomplete_beta">And
344 other failures.</a>)</span>
349 <span class="blue">Max = 3.8e+04ε (Mean = 2.66e+03ε)</span>
354 <span class="blue">Max = 4.07e+04ε (Mean = 2.86e+03ε)</span>
359 <span class="blue">Max = 8.59e+03ε (Mean = 277ε)</span>
365 <br class="table-break"><div class="table">
366 <a name="math_toolkit.sf_beta.ibeta_inv_function.table_ibetac_inv"></a><p class="title"><b>Table 8.23. Error rates for ibetac_inv</b></p>
367 <div class="table-contents"><table class="table" summary="Error rates for ibetac_inv">
380 GNU C++ version 7.1.0<br> linux<br> double
385 GNU C++ version 7.1.0<br> linux<br> long double
390 Sun compiler version 0x5150<br> Sun Solaris<br> long double
395 Microsoft Visual C++ version 14.1<br> Win32<br> double
402 Inverse incomplete beta
407 <span class="blue">Max = 0.977ε (Mean = 0.0976ε)</span><br>
408 <br> (<span class="emphasis"><em>Rmath 3.2.3:</em></span> <span class="red">Max
409 = 3.01e+132ε (Mean = 8.65e+130ε) <a class="link" href="../logs_and_tables/logs.html#errors_GNU_C_version_7_1_0_linux_double_ibetac_inv_Rmath_3_2_3_Inverse_incomplete_beta">And
410 other failures.</a>)</span>
415 <span class="blue">Max = 4.88e+04ε (Mean = 3.16e+03ε)</span>
420 <span class="blue">Max = 5.05e+04ε (Mean = 3.33e+03ε)</span>
425 <span class="blue">Max = 2.93e+03ε (Mean = 198ε)</span>
431 <br class="table-break"><div class="table">
432 <a name="math_toolkit.sf_beta.ibeta_inv_function.table_ibeta_inva"></a><p class="title"><b>Table 8.24. Error rates for ibeta_inva</b></p>
433 <div class="table-contents"><table class="table" summary="Error rates for ibeta_inva">
446 GNU C++ version 7.1.0<br> linux<br> double
451 GNU C++ version 7.1.0<br> linux<br> long double
456 Sun compiler version 0x5150<br> Sun Solaris<br> long double
461 Microsoft Visual C++ version 14.1<br> Win32<br> double
468 Inverse incomplete beta
473 <span class="blue">Max = 0.602ε (Mean = 0.0239ε)</span>
478 <span class="blue">Max = 377ε (Mean = 24.4ε)</span>
483 <span class="blue">Max = 438ε (Mean = 31.3ε)</span>
488 <span class="blue">Max = 242ε (Mean = 22.9ε)</span>
494 <br class="table-break"><div class="table">
495 <a name="math_toolkit.sf_beta.ibeta_inv_function.table_ibetac_inva"></a><p class="title"><b>Table 8.25. Error rates for ibetac_inva</b></p>
496 <div class="table-contents"><table class="table" summary="Error rates for ibetac_inva">
509 GNU C++ version 7.1.0<br> linux<br> double
514 GNU C++ version 7.1.0<br> linux<br> long double
519 Sun compiler version 0x5150<br> Sun Solaris<br> long double
524 Microsoft Visual C++ version 14.1<br> Win32<br> double
531 Inverse incomplete beta
536 <span class="blue">Max = 0.683ε (Mean = 0.0314ε)</span>
541 <span class="blue">Max = 382ε (Mean = 22.2ε)</span>
546 <span class="blue">Max = 315ε (Mean = 23.7ε)</span>
551 <span class="blue">Max = 408ε (Mean = 26.7ε)</span>
557 <br class="table-break"><div class="table">
558 <a name="math_toolkit.sf_beta.ibeta_inv_function.table_ibeta_invb"></a><p class="title"><b>Table 8.26. Error rates for ibeta_invb</b></p>
559 <div class="table-contents"><table class="table" summary="Error rates for ibeta_invb">
572 GNU C++ version 7.1.0<br> linux<br> double
577 GNU C++ version 7.1.0<br> linux<br> long double
582 Sun compiler version 0x5150<br> Sun Solaris<br> long double
587 Microsoft Visual C++ version 14.1<br> Win32<br> double
594 Inverse incomplete beta
599 <span class="blue">Max = 0.765ε (Mean = 0.0422ε)</span>
604 <span class="blue">Max = 407ε (Mean = 27.2ε)</span>
609 <span class="blue">Max = 407ε (Mean = 24.4ε)</span>
614 <span class="blue">Max = 409ε (Mean = 19.3ε)</span>
620 <br class="table-break"><div class="table">
621 <a name="math_toolkit.sf_beta.ibeta_inv_function.table_ibetac_invb"></a><p class="title"><b>Table 8.27. Error rates for ibetac_invb</b></p>
622 <div class="table-contents"><table class="table" summary="Error rates for ibetac_invb">
635 GNU C++ version 7.1.0<br> linux<br> double
640 GNU C++ version 7.1.0<br> linux<br> long double
645 Sun compiler version 0x5150<br> Sun Solaris<br> long double
650 Microsoft Visual C++ version 14.1<br> Win32<br> double
657 Inverse incomplete beta
662 <span class="blue">Max = 0.724ε (Mean = 0.0303ε)</span>
667 <span class="blue">Max = 317ε (Mean = 19.8ε)</span>
672 <span class="blue">Max = 369ε (Mean = 22.6ε)</span>
677 <span class="blue">Max = 271ε (Mean = 16.4ε)</span>
683 <br class="table-break"><h5>
684 <a name="math_toolkit.sf_beta.ibeta_inv_function.h2"></a>
685 <span class="phrase"><a name="math_toolkit.sf_beta.ibeta_inv_function.testing"></a></span><a class="link" href="ibeta_inv_function.html#math_toolkit.sf_beta.ibeta_inv_function.testing">Testing</a>
688 There are two sets of tests:
690 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
691 <li class="listitem">
692 Basic sanity checks attempt to "round-trip" from <span class="emphasis"><em>a,
693 b</em></span> and <span class="emphasis"><em>x</em></span> to <span class="emphasis"><em>p</em></span> or
694 <span class="emphasis"><em>q</em></span> and back again. These tests have quite generous
695 tolerances: in general both the incomplete beta and its inverses change
696 so rapidly, that round tripping to more than a couple of significant
697 digits isn't possible. This is especially true when <span class="emphasis"><em>p</em></span>
698 or <span class="emphasis"><em>q</em></span> is very near one: in this case there isn't
699 enough "information content" in the input to the inverse function
700 to get back where you started.
702 <li class="listitem">
703 Accuracy checks using high precision test values. These measure the accuracy
704 of the result, given exact input values.
708 <a name="math_toolkit.sf_beta.ibeta_inv_function.h3"></a>
709 <span class="phrase"><a name="math_toolkit.sf_beta.ibeta_inv_function.implementation_of_ibeta_inv_and_"></a></span><a class="link" href="ibeta_inv_function.html#math_toolkit.sf_beta.ibeta_inv_function.implementation_of_ibeta_inv_and_">Implementation
710 of ibeta_inv and ibetac_inv</a>
713 These two functions share a common implementation.
716 First an initial approximation to x is computed then the last few bits are
717 cleaned up using <a href="http://en.wikipedia.org/wiki/Simple_rational_approximation" target="_top">Halley
718 iteration</a>. The iteration limit is set to 1/2 of the number of bits
719 in T, which by experiment is sufficient to ensure that the inverses are at
720 least as accurate as the normal incomplete beta functions. Up to 5 iterations
721 may be required in extreme cases, although normally only one or two are required.
722 Further, the number of iterations required decreases with increasing <span class="emphasis"><em>a</em></span>
723 and <span class="emphasis"><em>b</em></span> (which generally form the more important use cases).
726 The initial guesses used for iteration are obtained as follows:
731 <div class="blockquote"><blockquote class="blockquote"><p>
732 <span class="inlinemediaobject"><img src="../../../equations/ibeta_inv5.svg"></span>
734 </p></blockquote></div>
736 We may wish to start from either p or q, and to calculate either x or y.
737 In addition at any stage we can exchange a for b, p for q, and x for y if
738 it results in a more manageable problem.
741 For <code class="computeroutput"><span class="identifier">a</span><span class="special">+</span><span class="identifier">b</span> <span class="special">>=</span> <span class="number">5</span></code> the initial guess is computed using the methods
745 Asymptotic Inversion of the Incomplete Beta Function, by N. M. <a href="http://homepages.cwi.nl/~nicot/" target="_top">Temme</a>.
746 Journal of Computational and Applied Mathematics 41 (1992) 145-157.
749 The nearly symmetrical case (section 2 of the paper) is used for
751 <div class="blockquote"><blockquote class="blockquote"><p>
752 <span class="inlinemediaobject"><img src="../../../equations/ibeta_inv2.svg"></span>
754 </p></blockquote></div>
756 and involves solving the inverse error function first. The method is accurate
757 to at least 2 decimal digits when <code class="literal">a = 5</code> rising to at least
758 8 digits when <code class="literal">a = 10<sup>5</sup></code>.
761 The general error function case (section 3 of the paper) is used for
763 <div class="blockquote"><blockquote class="blockquote"><p>
764 <span class="inlinemediaobject"><img src="../../../equations/ibeta_inv3.svg"></span>
766 </p></blockquote></div>
768 and again expresses the inverse incomplete beta in terms of the inverse of
769 the error function. The method is accurate to at least 2 decimal digits when
770 <code class="literal">a+b = 5</code> rising to 11 digits when <code class="literal">a+b = 10<sup>5</sup></code>.
771 However, when the result is expected to be very small, and when a+b is also
772 small, then its accuracy tails off, in this case when p<sup>1/a</sup> < 0.0025 then
773 it is better to use the following as an initial estimate:
775 <div class="blockquote"><blockquote class="blockquote"><p>
776 <span class="inlinemediaobject"><img src="../../../equations/ibeta_inv4.svg"></span>
778 </p></blockquote></div>
780 Finally the for all other cases where <code class="computeroutput"><span class="identifier">a</span><span class="special">+</span><span class="identifier">b</span> <span class="special">></span>
781 <span class="number">5</span></code> the method of section 4 of the paper
782 is used. This expresses the inverse incomplete beta in terms of the inverse
783 of the incomplete gamma function, and is therefore significantly more expensive
784 to compute than the other cases. However the method is accurate to at least
785 3 decimal digits when <code class="literal">a = 5</code> rising to at least 10 digits
786 when <code class="literal">a = 10<sup>5</sup></code>. This method is limited to a > b, and
787 therefore we need to perform an exchange a for b, p for q and x for y when
788 this is not the case. In addition when p is close to 1 the method is inaccurate
789 should we actually want y rather than x as output. Therefore when q is small
790 (<code class="literal">q<sup>1/p</sup> < 10<sup>-3</sup></code>) we use:
792 <div class="blockquote"><blockquote class="blockquote"><p>
793 <span class="inlinemediaobject"><img src="../../../equations/ibeta_inv6.svg"></span>
795 </p></blockquote></div>
797 which is both cheaper to compute than the full method, and a more accurate
801 When a and b are both small there is a distinct lack of information in the
802 literature on how to proceed. I am extremely grateful to Prof Nico Temme
803 who provided the following information with a great deal of patience and
804 explanation on his part. Any errors that follow are entirely my own, and
808 When a and b are both less than 1, then there is a point of inflection in
809 the incomplete beta at point <code class="computeroutput"><span class="identifier">xs</span>
810 <span class="special">=</span> <span class="special">(</span><span class="number">1</span> <span class="special">-</span> <span class="identifier">a</span><span class="special">)</span> <span class="special">/</span> <span class="special">(</span><span class="number">2</span> <span class="special">-</span> <span class="identifier">a</span>
811 <span class="special">-</span> <span class="identifier">b</span><span class="special">)</span></code>. Therefore if <code class="literal">p > I<sub>x</sub>(a,b)</code>
812 we swap a for b, p for q and x for y, so that now we always look for a point
813 x below the point of inflection <code class="computeroutput"><span class="identifier">xs</span></code>,
814 and on a convex curve. An initial estimate for x is made with:
816 <div class="blockquote"><blockquote class="blockquote"><p>
817 <span class="inlinemediaobject"><img src="../../../equations/ibeta_inv7.svg"></span>
819 </p></blockquote></div>
821 which is provably below the true value for x: <a href="http://en.wikipedia.org/wiki/Newton%27s_method" target="_top">Newton
822 iteration</a> will therefore smoothly converge on x without problems
823 caused by overshooting etc.
826 When a and b are both greater than 1, but a+b is too small to use the other
827 methods mentioned above, we proceed as follows. Observe that there is a point
828 of inflection in the incomplete beta at <code class="computeroutput"><span class="identifier">xs</span>
829 <span class="special">=</span> <span class="special">(</span><span class="number">1</span> <span class="special">-</span> <span class="identifier">a</span><span class="special">)</span> <span class="special">/</span> <span class="special">(</span><span class="number">2</span> <span class="special">-</span> <span class="identifier">a</span>
830 <span class="special">-</span> <span class="identifier">b</span><span class="special">)</span></code>. Therefore if <code class="literal">p > I<sub>x</sub>(a,b)</code>
831 we swap a for b, p for q and x for y, so that now we always look for a point
832 x below the point of inflection <code class="computeroutput"><span class="identifier">xs</span></code>,
833 and on a concave curve. An initial estimate for x is made with:
835 <div class="blockquote"><blockquote class="blockquote"><p>
836 <span class="inlinemediaobject"><img src="../../../equations/ibeta_inv4.svg"></span>
838 </p></blockquote></div>
840 which can be improved somewhat to:
842 <div class="blockquote"><blockquote class="blockquote"><p>
843 <span class="inlinemediaobject"><img src="../../../equations/ibeta_inv1.svg"></span>
845 </p></blockquote></div>
847 when b and x are both small (I've used b < a and x < 0.2). This actually
848 under-estimates x, which drops us on the wrong side of x for Newton iteration
849 to converge monotonically. However, use of higher derivatives and Halley
850 iteration keeps everything under control.
853 The final case to be considered if when one of a and b is less than or equal
854 to 1, and the other greater that 1. Here, if b < a we swap a for b, p
855 for q and x for y. Now the curve of the incomplete beta is convex with no
856 points of inflection in [0,1]. For small p, x can be estimated using
858 <div class="blockquote"><blockquote class="blockquote"><p>
859 <span class="inlinemediaobject"><img src="../../../equations/ibeta_inv4.svg"></span>
861 </p></blockquote></div>
863 which under-estimates x, and drops us on the right side of the true value
864 for Newton iteration to converge monotonically. However, when p is large
865 this can quite badly underestimate x. This is especially an issue when we
866 really want to find y, in which case this method can be an arbitrary number
867 of order of magnitudes out, leading to very poor convergence during iteration.
870 Things can be improved by considering the incomplete beta as a distorted
871 quarter circle, and estimating y from:
873 <div class="blockquote"><blockquote class="blockquote"><p>
874 <span class="inlinemediaobject"><img src="../../../equations/ibeta_inv8.svg"></span>
876 </p></blockquote></div>
878 This doesn't guarantee that we will drop in on the right side of x for monotonic
879 convergence, but it does get us close enough that Halley iteration rapidly
880 converges on the true value.
883 <a name="math_toolkit.sf_beta.ibeta_inv_function.h4"></a>
884 <span class="phrase"><a name="math_toolkit.sf_beta.ibeta_inv_function.implementation_of_inverses_on_th"></a></span><a class="link" href="ibeta_inv_function.html#math_toolkit.sf_beta.ibeta_inv_function.implementation_of_inverses_on_th">Implementation
885 of inverses on the a and b parameters</a>
888 These four functions share a common implementation.
891 First an initial approximation is computed for <span class="emphasis"><em>a</em></span> or
892 <span class="emphasis"><em>b</em></span>: where possible this uses a Cornish-Fisher expansion
893 for the negative binomial distribution to get within around 1 of the result.
894 However, when <span class="emphasis"><em>a</em></span> or <span class="emphasis"><em>b</em></span> are very small
895 the Cornish Fisher expansion is not usable, in this case the initial approximation
896 is chosen so that I<sub>x</sub>(a, b) is near the middle of the range [0,1].
899 This initial guess is then used as a starting value for a generic root finding
900 algorithm. The algorithm converges rapidly on the root once it has been bracketed,
901 but bracketing the root may take several iterations. A better initial approximation
902 for <span class="emphasis"><em>a</em></span> or <span class="emphasis"><em>b</em></span> would improve these
903 functions quite substantially: currently 10-20 incomplete beta function invocations
904 are required to find the root.
907 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
908 <td align="left"></td>
909 <td align="right"><div class="copyright-footer">Copyright © 2006-2019 Nikhar
910 Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos,
911 Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan
912 Råde, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg,
913 Daryle Walker and Xiaogang Zhang<p>
914 Distributed under the Boost Software License, Version 1.0. (See accompanying
915 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
920 <div class="spirit-nav">
921 <a accesskey="p" href="ibeta_function.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_beta.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="beta_derivative.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>