025_model-points.html

<section>
  <p>
    Model points are essential inputs in an actuarial cash flow model. 
    They represent individual objects - such as insurance policies or financial assets - for which cash flows are projected. 
    Understanding model points is crucial for structuring actuarial models efficiently. 
  </p>
  
  <p>In this post, we will explain what model points are, their role in modelling, and how to set them up properly.</p>

  <div class="content">
    <span class="content__title">Content:</span>
    <ol>
      <li><a href="#what_are">What are model points?</a></li>
      <li><a href="#working">Working with model points</a></li>
      <ul>
        <li><a href="#working_define">Define model point set</a></li>
        <li><a href="#working_read">Read data from model point</a></li>
      </ul>
    </ol>
  </div>
</section>

<section>
<h2 id="what_are">What are model points?</h2>

<p>In short, a model point represents an object for which the actuarial cash flow model will be evaluated.</p>

<p>If you model life insurance, model points may be policy data which contain information on policyholders (age, sum insured, fund value etc.).
  If you model assets, model points can include characteristics of financial assets such as bonds.
</p>

<p>In the past, it was common to group multiple objects (e.g. multiple policyholders) with similar characteristics into one model point.
  Thanks to that, the model could run faster. Nowadays, it's not so common, because grouping requires additional work and computers just got faster.
</p>

<p>In Python framework for actuarial cash flow models <a href="https://pypi.org/project/cashflower/" target="_blank">cashflower</a>, the following naming convention is used:</p>
<ul>
  <li><b>model point set</b> - a group of model points; it can have a form of a file or a database query result,</li>
  <li><b>model point</b> - one or multiple records that contain data on the given object (e.g. a policyholder or a financial asset),</li>
  <li><b>record</b> - a single row of data.</li>
</ul>

<p>In the example below, there are 5 policyholders.
  The policyholder with the identifier <span class="inline-code">2</span> is a 64-year old male who pays €270 premium.</p>

<div class="horizontal-center">
  <img 
    src="/static/img/blog/025/single_model_point_set.webp" 
    alt="Model point set in the form of a table, where rows represent model points" 
    width="495" height="414"
  >
</div>

<p>A cash flow model can have multiple model point sets.</p>

<div class="horizontal-center">
  <img 
  src="/static/img/blog/025/multiple_model_point_sets.webp" 
  alt="Multiple model point sets: policy, coverage, and fund, with model point data spread across multiple tables" 
  width="996" height="524"
  style="max-width: 100%; height: auto; display: block;"
  >
</div>

<p>The above model has 3 model point sets: <span class="inline-code">policy</span>, <span class="inline-code">coverage</span> and <span class="inline-code">fund</span>.
  The model point for the identifier <span class="inline-code">2</span> has 5 records
  (1 in <span class="inline-code">policy</span>, 2 in <span class="inline-code">coverage</span> and 2 in <span class="inline-code">fund</span>).</p>

</section>


<section>
<h2 id="working">Working with model points</h2>

<p>Cheatsheet for working with model points in the <a href="https://pypi.org/project/cashflower/" target="_blank">cashflower</a> package.</p>

<h3 id="working_define">Define model point set</h3>

<p>Model point sets are defined in the <span class="inline-code">input.py</span> script.
  To create a model point set, use the <span class="inline-code">ModelPointSet</span> class
  and provide a <span class="inline-code">pandas</span> data frame as an argument for the <span class="inline-code">data</span> parameter.</p>

<pre><code class="language-python"># input.py
from cashflower import ModelPointSet

policy = ModelPointSet(data=pd.DataFrame({
    "id": [1, 2, 3, 4, 5],
    "age": [27, 64, 45, 33, 82]
    "sex": ["F", "M", "M", "F", "F"],
    "premium": [500, 270, 340, 650, 120],
}), main=True, id_column="id")

coverage = ModelPointSet(data=pd.DataFrame({
    "id": [1, 2, 2, 3, 4, 5, 5],
    "sum_assured": [100_000, 80_000, 25_000, 120_000, 30_000, 120_000, 10_0000],
    "type": ["DEATH", "DEATH", "ILLNESS", "DEATH", "DEATH", "DEATH", "ILLNESS"],
}), main=False, id_column="id")

fund = ModelPointSet(data=pd.DataFrame({
    "id": [1, 1, 2, 2, 3, 4, 5],
    "code": ["AC", "X9", "D7", "BB", "EF", "T6", "ZE"],
    "units": [50, 25, 30, 10, 40, 100, 15],
}), main=False, id_column="id")
</code></pre>

<p>The <span class="inline-code">policy</span> model point set is the <span class="inline-code">main</span> model point set,
  which means that the model will loop over the rows of this dataset. Model point sets match with each other based on the <span class="inline-code">id</span> column.


<h3 id="working_read">Read data from model point</h3>

<p>To read a value from a model point, use the <span class="inline-code">get()</span> method of the <span class="inline-code">ModelPointSet</span> class.
  Provide a name of the attribute as an argument.
</p>

<pre><code class="language-python">policy.get("age")</code></pre>

<p>The model will read the value of the model point which is currently calculated.</p>

<pre><code class="language-python"># model.py
from cashflower import variable
from input import assumption, policy

@variable()
def mortality_rate(t):
    age = policy.get("age")
    sex = policy.get("sex")
    return assumption["mortality"].loc[age, sex]["rate"]
</code></pre>

<p>If the model point has multiple records, you can read them like this:</p>

<pre><code class="language-python">fund.get("fund_value", record_num=1)</code></pre>

<p>This code will get the value of <span class="inline-code">fund_value</span> for the <b>second</b> record of the currently evaluated model point (counting starts with 0 in Python!).</p>

<p>If model points have varying number of records, you can use e.g. <span class="inline-code">fund.model_point_data.shape[0]</span> to determine the number of records of the model point.</p>

<p>For example, to calculate the total value of fund value, use:</p>

<pre><code class="language-python"># model.py
@variable()
def total_fund_value(t):
    total_value = 0
    for i in range(0, fund.model_point_data.shape[0]):
        total_value += fund.get("fund_value", i)
    return total_value
</code></pre>

</section>

<br>

<p>Thank you for taking the time to read this blog post.
  If you have any comments or suggestions, please feel free to share them
  in the comment section below or on <a href="https://github.com/acturtle/cashflower/discussions" target="_blank">github</a>.</p>