031_model-variables.html

<section>
  <p>
    Model variables are fundamental to financial cash flow models, shaping how calculations unfold over time. 
    In this blog post, we will explore different types of model variables and demonstrate how to create them 
    using <a href="https://pypi.org/project/cashflower/" target="_blank">the cashflower package</a>. 
  </p>
  <p>    
    Understanding how to define and use model variables effectively is crucial for building accurate and flexible models. 
    Some variables change over time, while others remain constant. We will walk through both types, 
    showing how they function and how they interact within a cash flow model.
  </p>

  <div class="content">
    <span class="content__title">Content:</span>
    <ol>
      <li><a href="#define">Defining model variables</a></li>
      <li><a href="#regular">Time-dependent variable</a></li>
      <li><a href="#constant">Constant variable</a></li>
    </ol>
  </div>
</section>

<section>
<h2 id="define">Defining model variables</h2>

<p>To define a model variable, follow these steps:</p>
<ol>
  <li>define a function with the <span class="inline-code">t</span> parameter (or without any parameters),</li>
  <li>decorate the function with <span class="inline-code">@variable()</span>.</li>
</ol>

<p>Model variables can produce results per time and model point. While most are time-dependent,
  some remain constant throughout. Let's explore both types.</p>

<div class="horizontal-center" id="drawing">
  <img src="/static/img/blog/031/model-variables.webp" alt="Two model variables: one with varying values across periods and another with constant values across periods" width="409" height="326">
</div>

<p>Types of variables:</p>
<ul>
  <li>A - time-dependent variable,</li>
  <li>B - time-independent variable,</li>
</ul>

<p>We will guide you through creating both types of model variables in the sections below.</p>
</section>


<section>
<h2 id="regular">Time-dependent variable</h2>

<p>Time-dependent variables generate values for each future period. To create one,
define a function with the <span class="inline-code">t</span> parameter and
decorate it with <span class="inline-code">@variable()</span>.</p>

<p>For example:</p>

<pre><code class="language-python">@variable()
def cal_month(t):
    if t == 0:
        return runplan.get("valuation_month")
    if cal_month(t-1) == 12:
        return 1
    else:
        return cal_month(t-1) + 1
</code></pre>

<p>The variable can be called inside of another variable.</p>

<p>For example:</p>

<pre><code class="language-python">@variable()
def cal_year(t):
    # ...
    cal_month(t-1)
    # ...
</code></pre>
</section>


<section>
<h2 id="constant">Constant variable</h2>

<p>To define time-independent variables, create a function without any parameters.</p>

<pre><code class="language-python">@variable()
def elapsed_months():
    issue_year = policy.get("issue_year")
    issue_month = policy.get("issue_month")
    valuation_year = runplan.get("valuation_year")
    valuation_month = runplan.get("valuation_month")
    return (valuation_year - issue_year) * 12 + (valuation_month - issue_month)
</code></pre>

<p>Constant variables, like <span class="inline-code">elapsed_months</span>, maintain a consistent value throughout the projection,
  making them independent of time. To call such variables, there's no need to pass any arguments.</p>

<p>For example:</p>

<pre><code class="language-python">@variable()
def pol_month(t):
    # ...
    mnth = elapsed_months() % 12
    # ...
</code></pre>

<p>These variables are particularly useful for storing information that remains unchanged over time.</p>

</section>

<br>

<p>Thank you for reading this blog post! I hope it provided you with valuable insights.
  Feel free to leave a comment below or on <a href="https://github.com/acturtle/cashflower/discussions" target="_blank">github</a>
  to share your thoughts or ask any questions. Your feedback is greatly appreciated!
</p>