Skip to content

Commit c183e5a

Browse files
committed
Deployed ef85f87 with MkDocs version: 1.6.1
1 parent ec8f8f6 commit c183e5a

File tree

15 files changed

+1571
-76
lines changed

15 files changed

+1571
-76
lines changed

.DS_Store

0 Bytes
Binary file not shown.

api/applications/index.html

Lines changed: 630 additions & 15 deletions
Large diffs are not rendered by default.

api/models/index.html

Lines changed: 71 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -568,7 +568,7 @@ <h4 id="cpm.models.activation.Offset.compute" class="doc doc-heading">
568568

569569

570570
<h3 id="cpm.models.activation.ProspectUtility" class="doc doc-heading">
571-
<code class="highlight language-python"><span class="n">ProspectUtility</span><span class="p">(</span><span class="n">magnitudes</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">probabilities</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">alpha_pos</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">alpha_neg</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">lambda_loss</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">beta</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">delta</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">weighting</span><span class="o">=</span><span class="s1">&#39;tk&#39;</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span></code>
571+
<code class="highlight language-python"><span class="n">ProspectUtility</span><span class="p">(</span><span class="n">magnitudes</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">probabilities</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">alpha</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">beta</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">lambda_loss</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">gamma</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">delta</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">utility_curve</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">weighting</span><span class="o">=</span><span class="s1">&#39;tk&#39;</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span></code>
572572

573573
</h3>
574574

@@ -596,9 +596,8 @@ <h3 id="cpm.models.activation.ProspectUtility" class="doc doc-heading">
596596
)
597597
598598
<div class="doc-md-description">
599-
<p>The magnitudes of potential outcomes for each choice option.
600-
Should be a nested array where the outer dimension represents trials,
601-
followed by options within each trial, followed by potential outcomes within each option.</p>
599+
<p>A nested array where the outer dimension represents trials, with each trial
600+
containing the potential outcome magnitudes for each option.</p>
602601
</div>
603602
</li>
604603
<li>
@@ -608,30 +607,28 @@ <h3 id="cpm.models.activation.ProspectUtility" class="doc doc-heading">
608607
)
609608
610609
<div class="doc-md-description">
611-
<p>The probabilities of potential outcomes for each choice option.
612-
Should be a nested array where the outer dimension represents trials,
613-
followed by options within each trial, followed by potential outcomes within each option.</p>
610+
<p>A nested array (with the same shape as magnitudes) where each entry contains
611+
the probability of the corresponding outcome.</p>
614612
</div>
615613
</li>
616614
<li>
617-
<b><code>alpha_pos</code></b>
615+
<b><code>alpha</code></b>
618616
(<code><span title="float">float</span></code>, default:
619617
<code>1</code>
620618
)
621619
622620
<div class="doc-md-description">
623-
<p>The risk attitude parameter for non-negative outcomes, which determines the curvature of the utility function in the gain domain.
624-
If alpha_neg is undefined, alpha_pos will be used for both the gain and loss domains.</p>
621+
<p>The utility curvature parameter, used for both gains and losses.</p>
625622
</div>
626623
</li>
627624
<li>
628-
<b><code>alpha_neg</code></b>
625+
<b><code>beta</code></b>
629626
(<code><span title="float">float</span></code>, default:
630627
<code>None</code>
631628
)
632629
633630
<div class="doc-md-description">
634-
<p>The risk attitude parameter for negative outcomes, which determines the curvature of the utility function in the loss domain.</p>
631+
<p>An optional parameter for the utility function used by Tversky and Kahneman (1992) for losses, defaults to <code>alpha</code> if not provided.</p>
635632
</div>
636633
</li>
637634
<li>
@@ -641,17 +638,17 @@ <h3 id="cpm.models.activation.ProspectUtility" class="doc doc-heading">
641638
)
642639
643640
<div class="doc-md-description">
644-
<p>The loss aversion parameter, which scales the utility of negative outcomes relative to non-negative outcomes.</p>
641+
<p>The loss aversion parameter (scaling losses relative to gains).</p>
645642
</div>
646643
</li>
647644
<li>
648-
<b><code>beta</code></b>
645+
<b><code>gamma</code></b>
649646
(<code><span title="float">float</span></code>, default:
650647
<code>1</code>
651648
)
652649
653650
<div class="doc-md-description">
654-
<p>The discriminability parameter, which determines the curvature of the weighting function.</p>
651+
<p>The probability weighting curvature parameter (for gains with "tk" and both gains and losses with "power").</p>
655652
</div>
656653
</li>
657654
<li>
@@ -661,7 +658,17 @@ <h3 id="cpm.models.activation.ProspectUtility" class="doc doc-heading">
661658
)
662659
663660
<div class="doc-md-description">
664-
<p>The attractiveness parameter, which determines the elevation of the weighting function.</p>
661+
<p>The attractiveness parameter, which determines the elevation of the weighting function in <code>prelec</code> and <code>gw</code> weighting functions. In <code>tk</code>, it is the probability weighting for losses. Defaults to <code>gamma</code> if not provided.</p>
662+
</div>
663+
</li>
664+
<li>
665+
<b><code>utility_curve</code></b>
666+
(<code><span title="callable">callable</span></code>, default:
667+
<code>None</code>
668+
)
669+
670+
<div class="doc-md-description">
671+
<p>An optional utility function that takes the magnitude, alpha, and lambda_loss, and returns the utilities of each choice options. The default is a power utility function, see Notes.</p>
665672
</div>
666673
</li>
667674
<li>
@@ -671,7 +678,7 @@ <h3 id="cpm.models.activation.ProspectUtility" class="doc doc-heading">
671678
)
672679
673680
<div class="doc-md-description">
674-
<p>The definition of the weighting function. Should be one of 'tk', 'pd', or 'gw'.</p>
681+
<p>The definition of the weighting function. Should be one of 'tk', 'pd', or 'gw'. See Notes for details.</p>
675682
</div>
676683
</li>
677684
<li>
@@ -694,48 +701,70 @@ <h3 id="cpm.models.activation.ProspectUtility" class="doc doc-heading">
694701
<summary>Notes</summary>
695702
<p>The different weighting functions currently implemented are:</p>
696703
<pre><code>- `tk`: Tversky &amp; Kahneman (1992).
697-
- `pd`: Prelec (1998).
704+
- `prelec`: Prelec (1998).
698705
- `gw`: Gonzalez &amp; Wu (1999).
706+
- `power` : Simple power function: w(p) = p^gamma
699707
</code></pre>
700708
<p>Following Tversky &amp; Kahneman (1992), the expected utility U of a choice option is defined as:</p>
701-
<pre><code>U = sum(w(p) * u(x)),
702-
</code></pre>
703-
<p>where w is a weighting function of the probability p of a potential outcome,
704-
and u is the utility function of the magnitude x of a potential outcome.
705-
These functions are defined as follows (equations 6 and 5 respectively in Tversky &amp; Kahneman, 1992, pp. 309):</p>
706-
<pre><code>w(p) = p^beta / (p^beta + (1 - p)^beta)^(1/beta),
707-
708-
709-
u(x) = ifelse(x &gt;= 0, x^alpha_pos, -lambda * (-x)^alpha_neg),
710-
</code></pre>
711-
<p>where beta is the discriminability parameter of the weighting function;
712-
alpha_pos and alpha_neg are the risk attitude parameters in the gain and loss domains respectively,
713-
and lambda is the loss aversion parameter.</p>
709+
<div class="arithmatex">\[
710+
\mathcal{U} = \sum_{i=1}^{n} w(p_i) \cdot u(x_i)
711+
\]</div>
712+
<p>where <span class="arithmatex">\(w\)</span> is a weighting function of the probability p of a potential outcome,
713+
and <span class="arithmatex">\(u\)</span> is the utility function of the magnitude x of a potential outcome.
714+
The utility function <span class="arithmatex">\(u\)</span> is defined as a power function for both gains and losses. It is implemented
715+
after Equation 5 in Tversky &amp; Kahneman (1992):</p>
716+
<div class="arithmatex">\[
717+
u(x) =
718+
\begin{cases}
719+
x^\alpha &amp; \text{if } x \geq 0 \\
720+
-\lambda \cdot (-x)^\alpha &amp; \text{if } x &lt; 0
721+
\end{cases}
722+
\]</div>
723+
<p>where <span class="arithmatex">\(\alpha\)</span> is the utility curvature parameter, and <span class="arithmatex">\(\lambda\)</span> is the loss aversion parameter.
724+
The weighting function is implemented after Equation 6 in Tversky &amp; Kahneman (1992):</p>
725+
<div class="arithmatex">\[
726+
w(p) = \frac{p^\gamma}{(p^\gamma + (1 - p)^\gamma)^{1/\gamma}}
727+
\]</div>
728+
<p>where <code>gamma</code>, denoted via <span class="arithmatex">\(\gamma\)</span>, is the discriminability parameter of the weighting function.
729+
In the original formulation of Tversky &amp; Kahneman (1992), losses are weighted with a different parameter,
730+
<code>delta</code>, denoted via <span class="arithmatex">\(\delta\)</span>, that replaces <span class="arithmatex">\(\gamma\)</span> in the weighting function for losses.
731+
In the current implementation, whether it is a gain or less is determined by the sign of the corresponding
732+
magnitude.</p>
714733
<p>Several other definitions of the weighting function have been proposed in the literature,
715734
most notably in Prelec (1998) and Gonzalez &amp; Wu (1999).
716735
Prelec (equation 3.2, 1998, pp. 503) proposed the following definition:</p>
717-
<pre><code>w(p) = exp(-delta * (-log(p))^beta),
718-
</code></pre>
719-
<p>where delta and beta are the attractiveness and discriminability parameters of the weighting function.
736+
<div class="arithmatex">\[
737+
w(p) = \exp(-\delta \cdot (-\log(p))^\gamma)
738+
\]</div>
739+
<p>where <code>delta</code>, <span class="arithmatex">\(\delta\)</span>, and <code>gamma</code>, <span class="arithmatex">\(\gamma\)</span>, are the attractiveness and discriminability parameters of the weighting function.
720740
Gonzalez &amp; Wu (equation 3, 1999, pp. 139) proposed the following definition:</p>
721-
<pre><code>w(p) = (delta * p^beta) / ((delta * p^beta) + (1-p)^beta).
722-
</code></pre>
741+
<div class="arithmatex">\[
742+
w(p) = \frac{\delta \cdot p^\gamma}{\delta \cdot p^\gamma + (1 - p)^\gamma}
743+
\]</div>
723744
</details>
724745

725746
<p><span class="doc-section-title">Examples:</span></p>
726-
<div class="highlight"><pre><span></span><code><span class="gp">&gt;&gt;&gt; </span><span class="n">vals</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">40</span><span class="p">]),</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mi">10</span><span class="p">])],</span> <span class="n">dtype</span><span class="o">=</span><span class="nb">object</span><span class="p">)</span>
727-
<span class="gp">&gt;&gt;&gt; </span><span class="n">probs</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mf">0.95</span><span class="p">,</span> <span class="mf">0.05</span><span class="p">]),</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">])],</span> <span class="n">dtype</span><span class="o">=</span><span class="nb">object</span><span class="p">)</span>
728-
<span class="gp">&gt;&gt;&gt; </span><span class="n">prospect</span> <span class="o">=</span> <span class="n">ProspectUtility</span><span class="p">(</span>
729-
<span class="go"> magnitudes=vals, probabilities=probs, alpha_pos = 0.85, beta = 0.9</span>
747+
<div class="highlight"><pre><span></span><code><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span><span class="w"> </span><span class="nn">cpm.models.activations</span><span class="w"> </span><span class="kn">import</span> <span class="n">ProspectUtility</span>
748+
<span class="gp">&gt;&gt;&gt; </span><span class="n">magnitudes</span> <span class="o">=</span> <span class="p">[[</span><span class="mi">5</span><span class="p">,</span> <span class="mi">0</span><span class="p">],</span> <span class="p">[</span><span class="mi">10</span><span class="p">,</span> <span class="o">-</span><span class="mi">10</span><span class="p">]]</span>
749+
<span class="gp">&gt;&gt;&gt; </span><span class="n">probabilities</span> <span class="o">=</span> <span class="p">[[</span><span class="mf">0.8</span><span class="p">,</span> <span class="mf">0.2</span><span class="p">],</span> <span class="p">[</span><span class="mf">0.5</span><span class="p">,</span> <span class="mf">0.5</span><span class="p">]]</span>
750+
<span class="gp">&gt;&gt;&gt; </span><span class="n">model</span> <span class="o">=</span> <span class="n">ProspectUtility</span><span class="p">(</span>
751+
<span class="go"> magnitudes=magnitudes,</span>
752+
<span class="go"> probabilities=probabilities,</span>
753+
<span class="go"> alpha=0.88,</span>
754+
<span class="go"> lambda_loss=2.25,</span>
755+
<span class="go"> gamma=0.61,</span>
756+
<span class="go"> delta=1.0,</span>
757+
<span class="go"> weighting=&quot;tk&quot;</span>
730758
<span class="go"> )</span>
731-
<span class="gp">&gt;&gt;&gt; </span><span class="n">prospect</span><span class="o">.</span><span class="n">compute</span><span class="p">()</span>
732-
<span class="go">array([2.44583162, 7.07945784])</span>
759+
<span class="gp">&gt;&gt;&gt; </span><span class="n">expected_utilities</span> <span class="o">=</span> <span class="n">model</span><span class="o">.</span><span class="n">compute</span><span class="p">()</span>
760+
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">expected_utilities</span><span class="p">)</span>
733761
</code></pre></div>
734762

735763

736764
<details class="references" open>
737765
<summary>References</summary>
738766
<p>Gonzalez, R., &amp; Wu, G. (1999). On the shape of the probability weighting function. Cognitive psychology, 38(1), 129-166.</p>
767+
<p>Kahneman, D., &amp; Tversky, A. (1979). Prospect theory: An analysis of decision under risk. <em>Econometrica</em>, 47(2), 263–291.</p>
739768
<p>Prelec, D. (1998). The probability weighting function. Econometrica, 497-527.</p>
740769
<p>Tversky, A., &amp; Kahneman, D. (1992). Advances in prospect theory: Cumulative representation of uncertainty. Journal of Risk and uncertainty, 5, 297-323.</p>
741770
</details>

0 commit comments

Comments
 (0)