clarify project purpose and add epv docs

trollefson · Jul 2, 2019 · d7672c6 · d7672c6
1 parent 09021a3
commit d7672c6
Show file tree

Hide file tree

Showing 10 changed files with 55 additions and 6 deletions.
diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@
 [![Coverage Status](https://coveralls.io/repos/github/trollefson/elizur/badge.svg?branch=master)](https://coveralls.io/github/trollefson/elizur?branch=master)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
 
-Elizur is an open source finance library for actuaries, finance professionals, and students.  The library currently helps with calculating present values, future values, expected present values, life contingencies, and other common procedures performed by professionals and students.  The library is free of charge, open source, well tested, documented, and depends only on the Python 3 standard library at runtime.  The Elizur project is named after Elizur Wright.
+Elizur is an open source finance library for actuaries, finance professionals, and students.  The library currently helps with calculating present values, future values, expected present values, life contingencies, and other common procedures performed by professionals and students.  The library is intended to help with exam formula and other general finance calculations.  It is not a place for real world modeling solutions like IFRS17 or Solvency II.  The library will remain a library.  If you'd like to create a web ui or desktop application with Elizur please start a seperate project and include Elizur as a dependency.  The library is free of charge, open source, well tested, documented, and depends only on the Python 3 standard library at runtime.  The Elizur project is named after [Elizur Wright](https://en.wikipedia.org/wiki/Elizur_Wright).
 
 If you like Elizur, support the project by clicking the :star: above!
 
@@ -112,9 +112,7 @@ If you have questions, suggestions, or just want to talk about using Python join
 
 ## Contributing
 
-Do you want to help this project without contributing code?  Take our survey [here](https://www.surveymonkey.com/r/BZ55VPH).  
-
-Otherwise checkout the contributing guide [here](https://github.com/trollefson/elizur/blob/master/CONTRIBUTING.md) if you like to contribute code or raise issues.
+Checkout the contributing guide [here](https://github.com/trollefson/elizur/blob/master/CONTRIBUTING.md) if you'd like to contribute code or raise issues [here](https://github.com/trollefson/elizur/issues).
 
 ## New to Python?
 

diff --git a/docs/doctrees/environment.pickle b/docs/doctrees/environment.pickle
diff --git a/docs/doctrees/life/index.doctree b/docs/doctrees/life/index.doctree
diff --git a/docs/html/_sources/life/index.rst.txt b/docs/html/_sources/life/index.rst.txt
@@ -1,3 +1,6 @@
+.. automodule:: elizur.life
+    :members:
+
 Life
 ====
 .. toctree::

diff --git a/docs/html/genindex.html b/docs/html/genindex.html
@@ -240,13 +240,17 @@ <h2 id="D">D</h2>
 <h2 id="E">E</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
   <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="life/index.html#module-elizur.life">elizur.life (module)</a>
+</li>
       <li><a href="life/annuity.html#module-elizur.life.annuity">elizur.life.annuity (module)</a>
 </li>
   </ul></td>
   <td style="width: 33%; vertical-align: top;"><ul>
       <li><a href="life/util.html#module-elizur.life.util">elizur.life.util (module)</a>
 </li>
       <li><a href="life/table.html#elizur.life.table.LifeTable.ex">ex() (elizur.life.table.LifeTable method)</a>
+</li>
+      <li><a href="life/index.html#elizur.life.expected_present_value">expected_present_value() (in module elizur.life)</a>
 </li>
   </ul></td>
 </tr></table>
@@ -283,6 +287,8 @@ <h2 id="I">I</h2>
       <li><a href="life/annuity.html#elizur.life.annuity.increasing_annuity_pv">increasing_annuity_pv() (in module elizur.life.annuity)</a>
 </li>
       <li><a href="life/annuity.html#elizur.life.annuity.interest_rate">interest_rate() (in module elizur.life.annuity)</a>
+</li>
+      <li><a href="life/index.html#elizur.life.InvalidEPVInputs">InvalidEPVInputs</a>
 </li>
       <li><a href="life/util.html#elizur.life.util.InvalidInterestRate">InvalidInterestRate</a>
 </li>

diff --git a/docs/html/life/index.html b/docs/html/life/index.html
@@ -158,7 +158,41 @@
           <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
            <div itemprop="articleBody">
 
-  <div class="section" id="life">
+  <span class="target" id="module-elizur.life"></span><dl class="exception">
+<dt id="elizur.life.InvalidEPVInputs">
+<em class="property">exception </em><code class="sig-prename descclassname">elizur.life.</code><code class="sig-name descname">InvalidEPVInputs</code><a class="headerlink" href="#elizur.life.InvalidEPVInputs" title="Permalink to this definition">¶</a></dt>
+<dd><p>Custom exception raised for invalid expected present value inputs.</p>
+</dd></dl>
+
+<dl class="function">
+<dt id="elizur.life.expected_present_value">
+<code class="sig-prename descclassname">elizur.life.</code><code class="sig-name descname">expected_present_value</code><span class="sig-paren">(</span><em class="sig-param">cash_flows: Tuple[float], probabilities: Tuple[float], interest_rates: Tuple[float]</em><span class="sig-paren">)</span> &#x2192; float<a class="headerlink" href="#elizur.life.expected_present_value" title="Permalink to this definition">¶</a></dt>
+<dd><p>This function is useful for calculating variable streams of cash flows,
+interest rates, and probabilities.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Parameters</dt>
+<dd class="field-odd"><ul class="simple">
+<li><p><strong>cash_flows</strong> – payouts from time 0 to n, where time n is the last</p></li>
+<li><p><strong>payout</strong><strong>, </strong><strong>e.g.</strong><strong>,</strong> (<em>possible</em>) – </p></li>
+<li><p><strong>probabilities</strong> – probability of a cash flow occuring from time
+0 to n, e.g., (1p0, 2p1, 3p2, …, npn-1)</p></li>
+<li><p><strong>interest_rates</strong> – collection of interest rates to use for
+discounting, where each interest rate is for one
+period, e.g., (i0to1, i1to2, …, in-1ton)</p></li>
+</ul>
+</dd>
+<dt class="field-even">Returns</dt>
+<dd class="field-even"><p>The expected present value</p>
+</dd>
+</dl>
+<p class="rubric">Example</p>
+<p>Given the probabilities: 1p0 = 0.98, 2p1=0.94, 3p2=0.91</p>
+<p>annuity(x=0, i=0.07, n=3)
+expected_present_value((1, 1, 1), (0.98, 0.94, 0.91), (0.07, 0.07, 0.07))</p>
+<p>The two methods of calculated the present value of an annuity are the same</p>
+</dd></dl>
+
+<div class="section" id="life">
 <h1>Life<a class="headerlink" href="#life" title="Permalink to this headline">¶</a></h1>
 <div class="toctree-wrapper compound">
 <ul>

diff --git a/docs/html/objects.inv b/docs/html/objects.inv
diff --git a/docs/html/py-modindex.html b/docs/html/py-modindex.html
@@ -172,6 +172,11 @@ <h1>Python Module Index</h1>
        <td>
        <code class="xref">elizur</code></td><td>
        <em></em></td></tr>
+     <tr class="cg-1">
+       <td></td>
+       <td>&#160;&#160;&#160;
+       <a href="life/index.html#module-elizur.life"><code class="xref">elizur.life</code></a></td><td>
+       <em></em></td></tr>
      <tr class="cg-1">
        <td></td>
        <td>&#160;&#160;&#160;

diff --git a/docs/html/searchindex.js b/docs/html/searchindex.js
diff --git a/sphinx/life/index.rst b/sphinx/life/index.rst
@@ -1,3 +1,6 @@
+.. automodule:: elizur.life
+    :members:
+
 Life
 ====
 .. toctree::