CALCULATION ENGINES BEYOND EXCEL: PART 3
In Part 2 we expanded our one month illustration to a full year while moving the majority of business logic to simple functions. Next we will add tests to our project to reduce the risk of unintended changes.
By the end of this part, your code should look like this.
OUR PROJECT SO FAR
If you are following along closely, you should have a local project structure that looks like the following, you may have additional items like __pycache__/ within the directory. For simplicity I will not list the contents of the virtual environment.
illustrator/
venv/
.gitignore
functions.py
hello.py
README.md
simple.py
If you are using Git and an online repository solution like GitHub your online repository will not include the venv directory there nor other items captured within the .gitignore file.
Currently, our main script is contained within simple.py and leverages business logic we put in functions.py. Our rollforward itself is still located in simple.py and looks like this:
from functions import *
if __name__ == '__main__':
...
annual_premium = 1255.03
end_value = 0
policy_year = 0
for i in range(12*projection_years):
policy_year = calculate_policy_year(i+1)
start_value = calculate_start_value(end_value)
premium = calculate_premium(i+1, annual_premium)
premium_load = calculate_premium_load(premium, premium_load_rate)
expense_charge = calculate_per_policy_fee(annual_policy_fee) + calculate_per_unit_load(annual_unit_load[policy_year-1], face_amount)
value_for_naar = calculate_value_for_naar(start_value, premium, premium_load, expense_charge)
naar = calculate_naar(face_amount, naar_discount_rate, value_for_naar)
coi = calculate_coi(naar, annual_coi_rate[policy_year-1])
value_for_interest = calculate_value_for_interest(value_for_naar, coi)
interest = calculate_interest(value_for_interest, interest_rate)
end_value = calculate_end_value(value_for_interest, interest)
print(end_value)
From here we will add tests to our project that we can quickly run to ensure the functions in our rollforward behave as expected and do not break when we update the rest of the project.
RESTRUCTING FOR TESTS
Before we add tests to our project, we need to do a little reorganization of the structure.
First, delete hello.py which we created in Part 1 as a quick example of creating a function.
Next, in your illustrator directory create two folders: illustrator and tests. Within each of those directories create empty __init__.py files. Afterward, move your functions.py and simple.py within the second illustrator directory. Once this is done your project structure should look like the below (without showing the contents of venv) which is a bit closer to what some recommend for repository structure though not everything in the reference materials appears in our project.
illustrator/
illustrator/
__init__.py
functions.py
simple.py
tests/
__init__.py
venv/
.gitignore
README.md
A few things to point out here:
The outer illustrator is the name of our repository
The inner illustrator is the name of a module (now that we have an __init__.py file
Some reference materials might recommend using src for the name of the directory where we placed functions.py and simple.py
We should make some minor adjustments in simple.py and adjust our process for running the script
With these changes in place, we can start building some tests for our functionality. We are going to leverage the unittest module provided in the Python Standard Library since we are avoiding additional dependencies though I would recommend pytest if we did not place that restriction on ourselves. There is another Python Standard Library module we could use instead of unittest — we could use doctest but I do not think doctest scales particularly well.
In your tests directory add a new file test_functions.py with the following code:
import unittest
from illustrator import functions
class Test_Functions(unittest.TestCase):
def test_calculate_policy_year_month_1(self):
self.assertEqual(functions.calculate_policy_year(1),1)
There are a few new things going on here. We create a new class Test_Functions which is a subclass of the TestCase class found in the unittest module. Within our new class we create a method (functions inside classes are called methods) test_calculate_policy_year_month_1 which has a single parameter self. The method is going to run a check (self.assertEqual) that the result of our calculate_policy_year function and the value 1 are equal.
Without going down a rabbit-hole on objects and object-oriented programming let’s just remember that
When we define a class we are making a blueprint for an object, which may have data (attributes), actions (methods), or both
An object is an instance, an individual, of a class
Typically, a method f of an object O is called in the following manner and the object itself is passed to the method as the first argument: O.f()
When we define methods in the way described above we need to have at least one parameter for the function and it is common practice to use the word self to represent the object the method operates on
Now, with this in place and our earlier project reorganization we can run our tests very easily from a terminal in our outer illustrator directory like this:
(venv) PS ...\illustrator> python -m unittest
.
----------------------------------------------------------------------
Ran 1 test in 0.000s
OK
One great thing about the unittest module is that it has automatic test discovery so basically as long as each step of the way we have “test” at the start of everything the module will likely find our tests and run them (“tests” directory, “test_functions.py” file, “Test_Functions” class, “test_calculate_policy_year_month_1” method). Regarding the output, we do not get a lot of information running this way. The single period in the first output line in the terminal is for a test that was run (if we had 5 tests we would get 5 periods). If we wanted a little more information we could add “-v” after unittest like this:
(venv) PS ...\illustrator> python -m unittest -v
test_calculate_policy_year_month_1 (tests.test_functions.Test_Functions.test_calculate_policy_year_month_1) ... ok
----------------------------------------------------------------------
Ran 1 test in 0.000s
OK
This way we can see the tests that were run, where they were sourced, and the status. This can be helpful when you have a larger testbed.
Try updating the test to force a failure (e.g., try checking that the policy year for month 1 is equal to 2 since we know that should fail) and rerun the test. What happens? You should see something similar to the below:
(venv) PS ...\illustrator> python -m unittest -v
test_calculate_policy_year_month_1 (tests.test_functions.Test_Functions.test_calculate_policy_year_month_1) ... FAIL
======================================================================
FAIL: test_calculate_policy_year_month_1 (tests.test_functions.Test_Functions.test_calculate_policy_year_month_1)
----------------------------------------------------------------------
Traceback (most recent call last):
File "...\illustrator\tests\test_functions.py", line 8, in test_calculate_policy_year_month_1
self.assertEqual(functions.calculate_policy_year(1),2)
~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError: 1 != 2
----------------------------------------------------------------------
Ran 1 test in 0.001s
We see that our test does indeed fail and we get some information as to why — apparently 1 does not equal 2! Go ahead and fix your test so it makes sense and add the following tests:
...
def test_calculate_policy_year_month_12(self):
self.assertEqual(functions.calculate_policy_year(12),1)
def test_calculate_policy_year_month_13(self):
self.assertEqual(functions.calculate_policy_year(13),2)
def test_calculate_policy_year_month_1201(self):
self.assertEqual(functions.calculate_policy_year(1201),101)
These are a few additional simple tests for our policy year calculation function. If you rerun the tests you should get 4 passing tests. A few things to keep in mind when writing tests:
Tests should be independent (e.g., not depend on the outcome of another test)
Aim for a high amount of coverage of code paths (e.g., if your function has control flow to consider try testing all paths)
Your tests should cover boundary conditions
Ideally tests will cover error handling (we are ignoring error handling at this time)
Tests should test one thing
Add a few more tests:
...
def test_calculate_start_value(self):
self.assertEqual(functions.calculate_start_value(1.2345),1.2345)
def test_calculate_premium_month_1(self):
self.assertEqual(functions.calculate_premium(1, 1234.56),1234.56)
def test_calculate_premium_months_2to12(self):
for i in range(2,13):
self.assertEqual(functions.calculate_premium(i,1234.56),0)
def test_calculate_premium_months_1to1440(self):
for i in range(1440):
if (i+1) % 12 == 1:
self.assertEqual(functions.calculate_premium(i+1,1234.56),1234.56)
else:
self.assertEqual(functions.calculate_premium(i+1,1234.56),0)
def test_calculate_premium_load_noprem(self):
for r in [0, 0.1, 0.01, -1, 999]:
self.assertEqual(functions.calculate_premium_load(0,r),0)
def test_calculate_premium_load_0rate(self):
for p in [0, 0.1, 0.01, -1, 999, 1234.56]:
self.assertEqual(functions.calculate_premium_load(p, 0),0)
def test_calculate_premium_load_5pct(self):
p = [0, 0.1, 0.01, -1, 999, 1234.56]
pl = [0, 0.005, 0.0005, -0.05, 49.95, 61.728]
for i in range(len(p)):
# self.assertEqual may fail
self.assertAlmostEqual(functions.calculate_premium_load(p[i],0.05),pl[i])
The first two are more of the same but for different functions. The third test above introduces a loop so we can quickly check each how a function performs over a series of incremental values. The fourth test iterates over a much longer time period and introduces more control flow so we can quickly test that the function always pays premium in the first month of a policy year. The next two tests on premium loads utilize a loop process over specified values; the first is intended to check that the premium load function returns zero when the premium is zero regardless of the premium load rate and the second checks that when the rate is zero the function returns zero regardless of premium input values.
The last function tests multiple premium inputs against premium load outputs assuming a 5% premium load (notice how both lists are the same length with pl values equal to 5% of p values. However, since floating point values cannot always be represented perfectly in memory we need to use assertAlmostEqual instead of assertEqual to prevent test unintended test failures.
We leave it to you to build out the rest of the testbed using these examples for guidance. When completed, ensure the tests run and pass with expected outputs given specified inputs.
RUNNING OUR SCRIPT
I mentioned earlier that we would need to update our process for running our simple.py script — let’s address that now.
First, if you try to run the script as we have been you should receive a error like the below.
(venv) C:\...\illustrator> python simple.py
C:\...\illustrator\venv\scripts\python.exe:
can't open file 'C:\\...\\illustrator\\simple.py': [Errno 2] No such file or directory
The first path might look a little different if you do not have a virtual environment enabled, but the general result will be the same. This fails because we moved where simple.py is located and python is unable to find it. This has a very easy fix:
(venv) C:\...\illustrator> python illustrator\simple.py
132184.0426761172
Note this works because we have been providing a relative path reference to Python. We could provide the full path to our simple.py file but that would be cumbersome for our demonstrations here and we assume you are working in the same directory as your code.
Update your README.md file as well for this change.
AVOIDING BAD IMPORT PRACTICES
You may have noticed that in test_functions.py we used the following import statement:
from illustrator import functions
while in simple.py we used
from functions import *
This also impacts how we called the functions in their respective files. In test_functions.py we need to include the functions namespace (e.g., functions.calculate_policy_year(1)) whereas in simple.py we could just call the functions directly. What we do in simple.py is generally considered a bad practice and we should update the code to follow a similar approach as what is done in test_functions.py. Given our layout and that we do not have an installed package (this requires slightly more architecture) we need to update our import statement to the following:
import functions
Then we need to update the function calls. This might seem like we’re adding a bunch of unnecessary boilerplate code but using the * wildcard in the import statement imports everything directly into simple.py which is viewed as suboptimal for at least two reasons:
Importing everything can pollute your namespace with a bunch of unnecessary references and may create conflicts
The developer loses insight into where the referenced code comes from which can create maintenance headaches
For a few extra keystrokes I know I am happy to avoid these issues.
Don’t forget to save your files, commit to your Git repo, and push to your online repository!
If you are having difficulty with the code please refer to the v0.3 tagged version of this repository.
Have questions or feedback? Reach out to let us know!